> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evolvingmachines.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# evolve job

> Start, follow, and derive jobs.

```bash theme={null}
evolve job <command> [options]
```

Every command below takes the [global options](/cli-reference#global-options).

## job start

```bash theme={null}
evolve job start [options]
```

Start a job; add `--watch` to follow it. Exactly the options of [`evolve run`](/cli-reference/run).

## job list

```bash theme={null}
evolve job list [options]
```

List jobs, newest first: yours, or `--scope shared` for your organizations'.

<ParamField path="-l, --limit" type="n">
  Page size.
</ParamField>

<ParamField path="--cursor" type="c">
  Resume from a page cursor.
</ParamField>

<ParamField path="--columns" type="keys | all | help">
  Choose and order columns, comma-separated. `help` lists the keys.
</ParamField>

<ParamField path="-q, --quiet">
  Print only ids, one per line, for piping.
</ParamField>

<ParamField path="--no-trunc">
  Full cell content instead of one-line truncation.
</ParamField>

<ParamField path="--no-headers">
  Omit the header row in piped (TSV) output.
</ParamField>

<ParamField path="--search" type="text">
  Free-text filter over job name and dataset names.
</ParamField>

<ParamField path="--scope" type="my | shared">
  Visibility scope: `my`, what you created (the default), or `shared`, your organizations' rows that teammates created.
</ParamField>

```bash theme={null}
evolve job list --limit 20 -q
```

## job show

```bash theme={null}
evolve job show <id> [id...]
```

Show one or more jobs in full. It ends with a pass\@k block, one line per arm and dataset that has numbers; `--json` carries the raw `stats.evals[].pass_at_k`. An `analyze` row holds the embedded policy and an `analysis` row the tally with the analyzer's spend. An uploaded job prints its provider as `ported` and its spend as `reported $X.XX (N/M trials reporting)`.

## job trials

```bash theme={null}
evolve job trials <id> [options]
```

List a job's trials.

<ParamField path="-l, --limit" type="n">
  Page size.
</ParamField>

<ParamField path="--cursor" type="c">
  Resume from a page cursor.
</ParamField>

<ParamField path="--columns" type="keys | all | help">
  Choose and order columns, comma-separated. `help` lists the keys.
</ParamField>

<ParamField path="-q, --quiet">
  Print only ids, one per line, for piping.
</ParamField>

<ParamField path="--no-trunc">
  Full cell content instead of one-line truncation.
</ParamField>

<ParamField path="--no-headers">
  Omit the header row in piped (TSV) output.
</ParamField>

<ParamField path="--status" type="s1,s2,...">
  Filter by trial status, for example `INFRASTRUCTURE_ERROR`.
</ParamField>

<ParamField path="--dataset" type="name">
  Filter to one dataset's trials.
</ParamField>

```bash theme={null}
evolve job trials 3e1f9a2c-… --status INFRASTRUCTURE_ERROR,SCORING_ERROR
```

## job tasks

```bash theme={null}
evolve job tasks <id> [options]
```

Per-task rollup of a job: one row per task.

<ParamField path="-l, --limit" type="n">
  Page size.
</ParamField>

<ParamField path="--cursor" type="c">
  Resume from a page cursor.
</ParamField>

<ParamField path="--columns" type="keys | all | help">
  Choose and order columns, comma-separated. `help` lists the keys.
</ParamField>

<ParamField path="-q, --quiet">
  Print only ids, one per line, for piping.
</ParamField>

<ParamField path="--no-trunc">
  Full cell content instead of one-line truncation.
</ParamField>

<ParamField path="--no-headers">
  Omit the header row in piped (TSV) output.
</ParamField>

## job compare

```bash theme={null}
evolve job compare <id> <id> [...]
```

Compare two to ten jobs side by side.

## job cancel

```bash theme={null}
evolve job cancel <id>
```

Request cancellation of a job.

## job delete

```bash theme={null}
evolve job delete <id> [options]
```

Permanently delete a job you created: its trials, traces, analyses and stored files. It names the job, then asks. Another member of the organization is refused with `org_forbidden`; a live job, a running analysis wave or a live regrade refuses as on [jobs](/core-concepts/jobs#stop-cancel-delete).

<ParamField path="-y, --yes">
  Delete without a confirmation prompt. On a non-interactive stdin the command refuses without it, rather than guessing. With `--json` the receipt is `{"job_id", "trials_deleted", "analyses_deleted"}`.
</ParamField>

## job stop

```bash theme={null}
evolve job stop <id> --dataset <name>
```

Stop one dataset's live trials without cancelling the job. Trials already settled are reported as already terminal, and a dataset the job never spanned is refused. If the command fails part way (a rate limit, say), the report prints first, marked `PARTIAL` with the trials no answer came back for (`partial: true` and `unreported` under `--json`), then the error, exit 1; re-running the same command finishes the rest.

<ParamField path="--dataset" type="name" required>
  The dataset whose live trials to stop.
</ParamField>

## job resume

```bash theme={null}
evolve job resume <id> [options]
```

A new linked job over a terminal job's failed or stopped trials.

<ParamField path="-f, --filter-error-type" type="type">
  Failure types to resume, matched on the trial's exception type. Repeatable. Defaults to the standard failure set plus stopped trials.
</ParamField>

```bash theme={null}
evolve job resume 3e1f9a2c-… -f InfrastructureError
```

## job retry

```bash theme={null}
evolve job retry <id> [options]
```

A new linked job re-running selected trials: all of them, the failed ones only, or named ids.

<ParamField path="--failed-only">
  Only retry failed trials: `SCORING_ERROR`, `INFRASTRUCTURE_ERROR`, `BUDGET`, `INDETERMINATE`. Stopped and scored trials are not failures.
</ParamField>

<ParamField path="-t, --trial" type="trial-id">
  Retry exactly this trial. Repeatable, all or nothing: each must be settled, and the job may still be running. Not combinable with `--failed-only`.
</ParamField>

## job regrade

```bash theme={null}
evolve job regrade <id> [options]
```

Verifier-only re-run of a terminal job. The result is a job.

<ParamField path="--status" type="s1,s2,...">
  Only regrade source trials in these statuses.
</ParamField>

<ParamField path="--task" type="name">
  Only regrade source trials of this task.
</ParamField>

## job imports

```bash theme={null}
evolve job imports [options]
```

List your job imports (uploads), newest first. This is how an import id is found again.

<ParamField path="-l, --limit" type="n">
  Page size.
</ParamField>

<ParamField path="--cursor" type="c">
  Resume from a page cursor.
</ParamField>

<ParamField path="--columns" type="keys | all | help">
  Choose and order columns, comma-separated. `help` lists the keys.
</ParamField>

<ParamField path="-q, --quiet">
  Print only ids, one per line, for piping.
</ParamField>

<ParamField path="--no-trunc">
  Full cell content instead of one-line truncation.
</ParamField>

<ParamField path="--no-headers">
  Omit the header row in piped (TSV) output.
</ParamField>

<ParamField path="--status" type="QUEUED | RUNNING | COMPLETED | FAILED">
  Filter by import status.
</ParamField>

## job import

```bash theme={null}
evolve job import <import-id> [options]
```

Show one job import, an upload's record, with a `skipped` count and one line per skipped trial when the ingest left any out.

<ParamField path="--watch">
  Poll until the import settles: `COMPLETED`, and the job is printed, or `FAILED`.
</ParamField>

## job download

```bash theme={null}
evolve job download <id> [options]
```

Download the job's results, unpacked as the standard job-directory tree plus `evolve.json` records.

<ParamField path="-o, --output-dir" type="dir">
  Directory to unpack into. Defaults to the current directory. The tree lands in `<dir>/job-<id>/`.
</ParamField>

<ParamField path="--overwrite">
  Replace an existing `<dir>/job-<id>/`.
</ParamField>

## job grep

```bash theme={null}
evolve job grep <id> <pattern> [options]
```

Search every trial's parsed trace in one server-side pass and print one line per matching trial with its sampled events. The pattern grammar and the page semantics are on [`jobs().grep()`](/sdk-reference/jobs#grep).

<ParamField path="--type" type="event-type">
  Only search events of exactly this type.
</ParamField>

<ParamField path="-l, --limit" type="n" default="50">
  Per-trial match groups per page. Max 200.
</ParamField>

<ParamField path="--cursor" type="c">
  Resume after this trial id, the previous page's `nextCursor`.
</ParamField>

```bash theme={null}
evolve job grep 3e1f9a2c-… 'permission denied'
```

## Global options

<ParamField path="--json">
  Machine-readable JSON output.
</ParamField>

<ParamField path="--api-key" type="key">
  API key. Defaults to `$EVOLVE_API_KEY`.
</ParamField>

<ParamField path="--base-url" type="url">
  API base URL. Defaults to the Evolve dashboard API.
</ParamField>