# Chalk CLI Reference: Batch Jobs
source: https://docs.chalk.ai/cli#batch-jobs

Trigger and manage batch operations including [incremental ingestion](https://docs.chalk.ai/docs/sql#incremental-queries), [aggregate backfills](https://docs.chalk.ai/docs/aggregations), and scheduled data processing jobs.

## `chalk trigger`
source: https://docs.chalk.ai/cli?command=trigger

```bash
chalk trigger [flags]
```

Use the `trigger` command to run a resolver or a deployed scheduled aggregate backfill from the CLI.

In addition to [scheduling resolver executions](https://docs.chalk.ai/docs/resolver-cron), Chalk allows you to [trigger resolver executions](https://docs.chalk.ai/docs/runs) from the CLI. The `trigger` endpoint, also supported in Chalk's API clients, allows you to build custom integrations with other data orchestration tools like Airflow.

If you trigger a resolver that takes arguments, Chalk will sample the latest value of all [temporally-consistent](https://docs.chalk.ai/docs/temporal-consistency) feature values. Then, it will execute the resolver for each of those arguments.

Use `--env` to set additional environment variables on the pod that executes the run, in the same way `env_overrides` does for offline queries. The flag is repeatable.

Use `--scheduled-aggregate-backfill` to run a named scheduled aggregate backfill ahead of schedule. Planner options and environment overrides can be supplied for that run.

**Flags**

- `-r, --resolver <resolver>` (string)
  The resolver to trigger.
- `--persist-online <persist-online>` (bool, default `true`)
  Persist data to the online store, if features are eligible.
- `--persist-offline <persist-offline>` (bool, default `true`)
  Persist data to the offline store.
- `--idempotency-key <idempotency-key>` (string)
  Ensure that only one job will be kicked off per uniquely provided key.
- `--env <KEY=VALUE>` (string[], default `[]`)
  Environment variable to set on the triggered run, in KEY=VALUE form. Repeatable.
- `--scheduled-aggregate-backfill <name>` (string)
  Name of a deployed scheduled aggregate backfill.
- `--planner-option <KEY=VALUE>` (string[], default `[]`)
  Planner option in KEY=VALUE form. Repeatable; booleans and numbers are typed automatically.

**Example**

```
$ chalk trigger --resolver my.module.fn
ID:     j-2qtwuxpskm2pbg
Status: Received
URL:    https://chalk.ai/runs/j-2qtwuxpskm2pbg

$ chalk trigger --resolver my.module.fn --env CHALK_LOG_LEVEL=DEBUG --env MY_SETTING=value

$ chalk trigger --scheduled-aggregate-backfill daily_orders
$ chalk trigger --sab daily_orders --planner-option num_shards=4 --env MY_SETTING=value
```

## `chalk incremental status`
source: https://docs.chalk.ai/cli?command=incremental_status

```bash
chalk incremental status [flags]
```

Use the `incremental status` command to get progress state for an incremental resolver, scheduled query, scheduled aggregate backfill, or materialized feature view.

- **Max Ingested Timestamp**: the latest timestamp found in the input data on the previous run.
- **Last Execution Timestamp**: the most recent execution time.

A materialized feature view reports one row per feature instead:

- **Materialized Through**: how far that feature has been filled. A feature that has never been filled shows no timestamp, because its next fill reads it from the beginning.
- **Updated At**: when the feature's watermark was last written -- by a fill that read it, whether or not it advanced, or by `chalk incremental set`. A feature whose source received no new rows still has this advanced, which is what separates it from one no fill is reading.

A row an earlier configuration left behind has no feature name to show, and is addressed by the persistence key the table lists it under.

**Flags**

- `-r, --resolver <resolver>` (string)
  Name of an incremental resolver.
- `-q, --scheduled-query <scheduled-query>` (string)
  Name of a scheduled query.
- `--scheduled-aggregate-backfill <name>` (string)
  Name of a deployed scheduled aggregate backfill.
- `--materialized-feature-view <namespace>` (string)
  Namespace of a materialized feature view, whose fill tracks a watermark per feature. (alias: --mfv)
- `--feature <fqn[=ts]>` (string[], default `[]`)
  A feature of --materialized-feature-view, by FQN. Repeatable. Give one feature its own watermark as `fqn=timestamp`; a bare fqn takes --max-ingested-ts. Defaults to every feature the view materializes.
- `--persistence-key <key[=ts]>` (string[], default `[]`)
  A feature of --materialized-feature-view, by the persistence key its row is stored under. Repeatable. For a row an earlier configuration left behind, which no feature name reaches. Reads and drops only -- a write names features with --feature.

**Example**

```
$ chalk incremental status --resolver my.module.fn
Resolver:                 my.module.fn
Environment:              my_environment_id
Max Ingested Timestamp:   2023-01-01T09:30:00+00:00
Last Execution Timestamp: N/A
$ chalk incremental status --sab daily_orders
$ chalk incremental status --mfv wide_demo
$ chalk incremental status --mfv wide_demo --feature wide_demo.email
$ chalk incremental status --mfv wide_demo --config-fingerprint 4821993017264418
```

## `chalk incremental drop`
source: https://docs.chalk.ai/cli?command=incremental_drop

```bash
chalk incremental drop [flags]
```

Use the `incremental drop` command to clear progress state for an incremental resolver, scheduled query, scheduled aggregate backfill, or materialized feature view.

This erases the stored timestamps used to track incremental progress. Workloads that use this state will begin their next run without a stored lower bound.

A materialized feature view tracks a watermark per feature. Without `--feature` the whole feature view is cleared, including rows an earlier configuration left behind; with it, only the named features are cleared and their next fill re-reads from the beginning.

**Flags**

- `-r, --resolver <resolver>` (string)
  Name of an incremental resolver.
- `-q, --scheduled-query <scheduled-query>` (string)
  Name of a scheduled query.
- `--scheduled-aggregate-backfill <name>` (string)
  Name of a deployed scheduled aggregate backfill.
- `--materialized-feature-view <namespace>` (string)
  Namespace of a materialized feature view, whose fill tracks a watermark per feature. (alias: --mfv)
- `--feature <fqn[=ts]>` (string[], default `[]`)
  A feature of --materialized-feature-view, by FQN. Repeatable. Give one feature its own watermark as `fqn=timestamp`; a bare fqn takes --max-ingested-ts. Defaults to every feature the view materializes.
- `--persistence-key <key[=ts]>` (string[], default `[]`)
  A feature of --materialized-feature-view, by the persistence key its row is stored under. Repeatable. For a row an earlier configuration left behind, which no feature name reaches. Reads and drops only -- a write names features with --feature.

**Example**

```
$ chalk incremental drop --resolver my.module.fn
Successfully cleared incremental progress state
$ chalk incremental drop --sab daily_orders
$ chalk incremental drop --mfv wide_demo
$ chalk incremental drop --mfv wide_demo --feature wide_demo.email
$ chalk incremental drop --mfv wide_demo --persistence-key wide_demo.email~iv2
```

## `chalk incremental set`
source: https://docs.chalk.ai/cli?command=incremental_set

```bash
chalk incremental set [flags]
```

Use the `incremental set` command to set progress state for an incremental resolver, scheduled query, scheduled aggregate backfill, or materialized feature view.

- `max_ingested_ts` represents the latest timestamp found in the input data on the previous run.
- `last_execution_ts` represents the most recent execution time.

Both values must be ISO-8601 timestamps with a time zone specified.

A materialized feature view tracks a watermark per feature, and only `max_ingested_ts` applies to it: the companion timestamp there records when a fill last read each feature, which the fill sets itself. Give one feature its own time as `--feature fqn=timestamp` to rewind several features to different points in a single call, which is what repairing a partial fill needs. Without `--feature` every feature already recorded is set to the same value, which reads the view first and so races a running fill -- prefer naming features.

**Flags**

- `-r, --resolver <resolver>` (string)
  Name of an incremental resolver.
- `-q, --scheduled-query <scheduled-query>` (string)
  Name of a scheduled query.
- `--scheduled-aggregate-backfill <name>` (string)
  Name of a deployed scheduled aggregate backfill.
- `--materialized-feature-view <namespace>` (string)
  Namespace of a materialized feature view, whose fill tracks a watermark per feature. (alias: --mfv)
- `--feature <fqn[=ts]>` (string[], default `[]`)
  A feature of --materialized-feature-view, by FQN. Repeatable. Give one feature its own watermark as `fqn=timestamp`; a bare fqn takes --max-ingested-ts. Defaults to every feature the view materializes.
- `--persistence-key <key[=ts]>` (string[], default `[]`)
  A feature of --materialized-feature-view, by the persistence key its row is stored under. Repeatable. For a row an earlier configuration left behind, which no feature name reaches. Reads and drops only -- a write names features with --feature.
- `--max-ingested-ts <max-ingested-ts>` (string)
  Latest timestamp found in ingested data (ISO 8601 Timestamp).
- `--last-execution-ts <last-execution-ts>` (string)
  Timestamp of the latest run (ISO 8601 Timestamp).

**Example**

```
$ chalk incremental set --resolver my.module.fn --max-ingested-ts "2023-01-01T09:30:00Z"
Successfully updated incremental progress state
$ chalk incremental set --sab daily_orders --max-ingested-ts "2026-08-24T00:00:00Z"
$ chalk incremental set --mfv wide_demo --feature wide_demo.email --max-ingested-ts "2026-06-30T00:00:00Z"
$ chalk incremental set --mfv wide_demo \
    --feature wide_demo.email=2026-06-30T00:00:00Z \
    --feature wide_demo.score=2026-07-15T00:00:00Z
```

## `chalk aggregate backfill`
source: https://docs.chalk.ai/cli?command=aggregate_backfill

```bash
chalk aggregate backfill [flags]
```

Use the `aggregate backfill` command to backfill a materialized window aggregation.

By default the backfill reads from the resolver that feeds the aggregation. Pass `--input-sql` to supply a SQL query as the root data source instead, which lets you backfill a specific population rather than every row the resolver would return.

Pass `--branch` to plan and run the backfill with that branch's latest deployment while writing the tiles to the environment's primary stores. This overwrites the tiles that production queries read with tiles computed by the branch's code, so use it to backfill a fix before promoting it. Branch backfills run as one job per planned sub-backfill and do not support `--num-shards`.

**Flags**

- `--feature <feature>` (string[], default `[]`)
  The names of the feature to backfill. Chalk will backfill potentially many aggregations for a single feature.
- `--lower-bound <lower-bound>` (string)
  An [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) instant string to set the lower bound on the feature time above which to backfill.
- `--upper-bound <upper-bound>` (string)
  An [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) instant string to set the upper bound on the feature time below which to backfill.
- `--resolver <resolver>` (string)
  The resolver to use for backfilling.
- `--input-sql <input-sql>` (string)
  A SQL query that selects the population to backfill, used as the root data source instead of a resolver. Mutually exclusive with --resolver. May be given inline or as '@path/to/query.sql' to read the query from a file.
- `--tag <tag>` (string[], default `[]`)
  Resolver tags to prefer when running the backfill. May be specified multiple times.
- `--store-offline <store-offline>` (bool, default `false`)
  If set, the backfill publishes precomputed aggregate tiles to offline storage. Unless --store-online is also passed, the tiles are written to offline storage instead of the online store. Requires both --lower-bound and --upper-bound as [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) instant strings
- `--store-online <store-online>` (bool, default `true`)
  Whether the backfill writes aggregate state to the online store. When omitted, the backfill writes to the online store unless --store-offline is set. Pass --store-online alongside --store-offline to write both stores from one backfill, or --store-online=false on its own for a compute-only run that materializes tiles into the job's dataset without writing to either store.
- `--store-online-summaries <store-online-summaries>` (bool, default `false`)
  If set, the backfill publishes online summaries. Unless --store-online is also passed, it does not write ordinary online buckets.
- `--allow-empty-tiles <allow-empty-tiles>` (bool, default `false`)
  If set, offline tile backfills may publish empty tiles. Requires --store-offline.
- `--plan <plan>` (bool, default `false`)
  If set, the command will print the plan of the backfill without executing it. The output will show the expected number of tiles to be backfilled and anticipated storage needs.
- `--exact <exact>` (bool, default `false`)
  If true, the backfill will execute the underlying SQL source to determine the exact number of rows that need to migrate.
- `--num-shards <count>` (int, default `0`)
  Split each planned backfill's window into at most this many bucket-aligned, time-sharded jobs. Must be greater than 1. The server picks the actual count from its per-shard window-width policy, so every shard stays aligned to the aggregation's bucket grid. Use it when a single job over the whole window runs out of memory or disk. Requires an environment with job-queue execution enabled; omitted, the backfill runs as a single job.
- `--planner-option <KEY=VALUE>` (string[], default `[]`)
  Planner option applied to every job of the backfill, in KEY=VALUE form. Repeatable.
- `--resource-group <resource-group>` (string)
  Specify the resource group to run the query against.

**Example**

```
$ chalk aggregate backfill --feature user.transaction_sum

$ chalk aggregate backfill --feature user.transaction_sum --input-sql "select id, amount, ts from transactions where merchant_id = 42"

$ chalk aggregate backfill --feature user.transaction_sum --input-sql @population.sql

$ chalk aggregate backfill --feature user.transaction_sum --lower-bound 2024-01-01T00:00:00.000Z --upper-bound 2025-01-01T00:00:00.000Z --num-shards 8

$ chalk aggregate backfill --feature user.transaction_sum --planner-option coalesce_summary_tile_tables=true

$ chalk aggregate backfill --feature user.transaction_sum --branch my-fix
```

## `chalk aggregate list`
source: https://docs.chalk.ai/cli?command=aggregate_list

```bash
chalk aggregate list [flags]
```

List all materializations.

**Example**

```
$ chalk aggregate list
 Series  Namespace    Group                Agg     Bucket  Retention  Aggregation  Dependent Features
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 1       transaction  user_id merchant_id  amount  1d      30d        sum          user.txn_sum_by_merchant merchant.txn_sum_by_user
 1       transaction  user_id merchant_id  amount  1d      30d        count        user.txn_count_by_merchant
 2       transaction  user_id              amount  1d      30d        sum          user.txn_sum
```

## `chalk jobs list`
source: https://docs.chalk.ai/cli?command=jobs_list

```bash
chalk jobs list [flags]
```

Use the `chalk jobs list` command to list information about jobs in the queue for your environment.

**Flags**

- `--state <state>` (string)
  Filter jobs by state (scheduled, running, completed, failed, canceled, not_ready).
- `--kind <kind>` (string)
  Filter jobs by kind (async_offline_query).
- `--limit <limit>` (int, default `50`)
  Maximum number of jobs to return.
- `--offset <offset>` (int, default `0`)
  Offset for pagination.

**Example**

```
$ chalk jobs list
$ chalk jobs list --state running
$ chalk jobs list --kind async_offline_query --limit 10
```

## `chalk jobs get`
source: https://docs.chalk.ai/cli?command=jobs_get

```bash
chalk jobs get <job-id>
```

Use the `chalk jobs get` command to retrieve detailed information about a specific job by its ID.

**Example**

```
$ chalk jobs get 123
$ chalk jobs get 456 --json
```

## `chalk jobs submit`
source: https://docs.chalk.ai/cli?command=jobs_submit

```bash
chalk jobs submit [flags]
```

Use the `chalk jobs submit` command to enqueue a new job in the data-plane job queue for the active environment.

Either pass `--kind`, `--resource-group`, and `--deployment-id` explicitly, or pass `--from-job <id>` to clone those values (plus args, routing metadata, and env_payload) from an existing job in the queue. Explicit flags always override values pulled from `--from-job`. `--operation-id` defaults to a new UUID.

**Flags**

- `--from-job <job-id>` (int, default `-1`)
  Copy kind, resource group, routing metadata, and args from an existing job id. Explicit flags override the copied values; --operation-id defaults to a new UUID.
- `--kind <kind>` (string)
  Kind of job to enqueue. One of: async_offline_query, scheduled_query, script_task, chalksql_run, dataframe_run. Required unless --from-job is set.
- `--resource-group <resource-group>` (string)
  Resource group the job should run under. Required unless --from-job is set.
- `--operation-id <operation-id>` (string)
  Operation ID to associate with the job. If unset, a new UUID is generated.
- `--mainline-deployment-id <deployment-id>` (string)
  Mainline deployment ID. Defaults to --deployment-id.
- `--job-name <name>` (string)
  Optional job name recorded on the job_queue row.
- `--job-index <index>` (int, default `-1`)
  Optional job index within the operation.
- `--fetch-priority <priority>` (int, default `-1`)
  Optional fetch priority.
- `--workflow-execution-id <workflow-id>` (string)
  Optional workflow execution ID to group jobs.
- `--num-workers <count>` (int, default `-1`)
  If > 0 and less than num jobs in operation, gates worker concurrency (job starts in WAITING until workers pick it up).
- `--deployment-id <deployment-id>` (string)
  Deployment ID for the worker pod to boot (args.deployment_id). Required unless --from-job is set.
- `--branch-name <branch>` (string)
  Optional branch name to target.
- `--override-source-uri <uri>` (string)
  Optional source URI override.
- `--max-attempts <n>` (int, default `-1`)
  Max attempts for the job before it is marked failed.
- `--enable-profiling <enable-profiling>` (bool, default `false`)
  Enable profiling for the job.
- `--completion-deadline-seconds <seconds>` (int, default `-1`)
  Per-attempt completion deadline in seconds.
- `--retry-on-completion-deadline <retry-on-completion-deadline>` (bool, default `false`)
  Retry when the per-attempt completion deadline is exceeded.
- `--operation-completion-deadline-seconds <seconds>` (int, default `-1`)
  Operation-level completion deadline in seconds.
- `--retry-on-operation-completion-deadline <retry-on-operation-completion-deadline>` (bool, default `false`)
  Retry when the operation-level completion deadline is exceeded.
- `--env <KEY=VALUE>` (string[], default `[]`)
  Environment payload entry in `KEY=VALUE` form. Repeatable. Merged into env_payload copied from --from-job.
- `--detach <detach>` (bool, default `false`)
  Detach the enqueued job from its source workflow: clears workflow_execution_id so the job runs as a standalone fragment outside its original workflow.

**Example**

```
$ chalk jobs submit \
    --kind async_offline_query \
    --resource-group default \
    --deployment-id dpl_abc123

# Re-enqueue an existing job under a new operation ID.
$ chalk jobs submit --from-job 800
```

## `chalk workflows list`
source: https://docs.chalk.ai/cli?command=workflows_list

```bash
chalk workflows list [flags]
```

Use the `chalk workflows list` command to list workflow executions in the active environment. Filter by deployment, kind, status, or a substring match on the workflow ID.

**Flags**

- `--deployment-id <deployment-id>` (string)
  Filter workflows by deployment ID.
- `--kind <kind>` (string)
  Filter workflows by kind (manual, cron, scheduled_query).
- `--status <status>` (string)
  Filter workflows by status (queued, working, completed, failed, canceled).
- `--id-filter <substring>` (string)
  Substring match filter on workflow execution ID.
- `--limit <limit>` (int, default `50`)
  Maximum number of workflows to return.
- `--offset <offset>` (int, default `0`)
  Offset for pagination.

**Example**

```
$ chalk workflows list
$ chalk workflows list --status working
$ chalk workflows list --kind cron --limit 10
```

## `chalk workflows get`
source: https://docs.chalk.ai/cli?command=workflows_get

```bash
chalk workflows get <workflow-execution-id>
```

Use the `chalk workflows get` command to retrieve details about a specific data-plane workflow execution by its ID.

**Example**

```
$ chalk workflows get wf_01hxyz...
$ chalk workflows get wf_01hxyz... --json
```

## `chalk workflows get_graph`
source: https://docs.chalk.ai/cli?command=workflows_get_graph

```bash
chalk workflows get-graph <workflow-execution-id>
```

Use the `chalk workflows get-graph` command to retrieve the operation-level DAG (nodes and edges) for a data-plane workflow execution.

**Example**

```
$ chalk workflows get-graph wf_01hxyz...
$ chalk workflows get-graph wf_01hxyz... --json
```
