> ## 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.

# CLI reference

> Every verb of the evolve command, from its own help output.

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

The `evolve` command starts jobs and reads everything back. Every verb accepts `--json` for machine-readable output, and `-h` or `--help` prints its flags under short headings, with defaults, and one to three examples.

## Verbs

| Verb                                | What it does                                                            |
| ----------------------------------- | ----------------------------------------------------------------------- |
| [`run`](/cli-reference/run)         | Start a job. Add `--watch` to follow it. The short form of `job start`. |
| [`analyze`](/cli-reference/analyze) | Analyze a finished job's trial traces against a rubric.                 |
| [`check`](/cli-reference/check)     | Check task quality against a rubric.                                    |
| [`upload`](/cli-reference/upload)   | Upload a job directory as a finished job.                               |

## Command groups

| Group                                 | Commands                                                                                                                                                 |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`skills`](/cli-reference/skills)     | `list`, `get`, `path`, `install`                                                                                                                         |
| [`job`](/cli-reference/job)           | `start`, `list`, `show`, `trials`, `tasks`, `compare`, `cancel`, `delete`, `stop`, `resume`, `retry`, `regrade`, `imports`, `import`, `download`, `grep` |
| [`trial`](/cli-reference/trial)       | `show`, `trace`, `download`, `retry`, `regrade`, `stop`                                                                                                  |
| [`analysis`](/cli-reference/analysis) | `list`, `show`, `trace`, `download`                                                                                                                      |
| [`check`](/cli-reference/check)       | `list`, `show`, `trace`, `download`                                                                                                                      |
| [`dataset`](/cli-reference/dataset)   | `list`, `show`, `check`, `publish`, `watch`, `download`, `activate`                                                                                      |
| [`skill`](/cli-reference/skill)       | `list`, `upload`, `show`, `delete`                                                                                                                       |
| [`agent`](/cli-reference/agent)       | `list`, `show`, `add`, `remove`                                                                                                                          |
| [`auth`](/cli-reference/auth)         | `status`, `org list`, `org show`                                                                                                                         |
| [`secrets`](/cli-reference/secrets)   | `set`, `list`, `delete`                                                                                                                                  |

The singular noun is canonical; `jobs`, `trials`, `analyses` and `datasets` are hidden aliases, as are `secret` for `secrets` and `ls` for `list`. `skills` is not the plural of `skill`: it is the group that serves the bundled skills to your coding agent. `agents` is not an alias: it is reserved for the managed-agents CLI and refuses, pointing at `evolve agent`.

## Global options

These work on every command.

<ParamField path="--json">
  Machine-readable JSON output. A refusal then prints one `{"error": {...}}` object on stdout with the server's `code`, `message`, `param`, `details`, `retryAfterSec` and `request_id` when present.
</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>

<ParamField path="-v, --version">
  Print the CLI version.
</ParamField>

## Ids

Every verb that takes an id (`job`, `trial`, `analysis`, `check` with a check id or a task check id, `skill`) also takes an unambiguous prefix of at least 8 characters. A prefix that matches nothing or more than one row is refused naming the candidates. A full id is never prefix-matched, `name:<skill-name>` is a name, and a job import id is taken as printed.

A trial prefix is resolved against every trial of every job in scope, so on an account with many jobs the lookup can hit the rate limit; the full id, which `evolve job trials <job>` prints, always works.

## Output

Human tables on a TTY, tab-separated rows when piped, `--json` for the machine shape (NDJSON under `--watch`), and `-q` for ids only. `--no-trunc` disables cell truncation and `--no-headers` drops the header row from piped output. A money cell carries its state: `$0.06` is final, `at least $0.06` is still being written, `-` means not measured yet.

`--columns` chooses and orders list columns, comma-separated; `--columns help` prints the keys. For `job list` they are `id`, `name`, `status`, `datasets`, `agents`, `trials`, `spent`, `started`; for `job trials` `task`, `agent`, `attempt`, `status`, `reward`, `spent`, `tokens`, `gpu`, `id`; for `analysis list` `id`, `status`, `task`, `job`, `trial`, `model`, `attempts`, `spent`, `created`, `finished`.

## Listing flags

Every `list` command, and `job trials`, `job tasks` and `job imports`, share one set of paging and formatting flags. Two take only the formatting flags, not `-l` or `--cursor`: `auth org list` and `secrets list`.

<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>

## Scope

`--scope` on `job list`, `analysis list` and `check list` is `my`, what you created and the default, or `shared`, your organizations' rows that teammates created. `all` is refused. Every id printed under either scope resolves on its `show`, `trace` and `download`; an id outside your organizations answers the noun's not-found code, exactly like an id that does not exist.

## Values

A flag's value may begin with `-`, such as `-x '-*'` or a negative number. Only a token that spells another flag of the same command is refused, and the refusal shows the `--flag=value` form. A typo in `--stream`, `--status`, `--scope` or `run`'s `-e` is a usage error naming the legal values, before any request.

## Exit codes

`0` on success (with `--watch`: the job `COMPLETED`, a publish settled `READY`, every analysis completed, no task check errored). `1` on a runtime or API failure (with `--watch`: `FAILED` or `CANCELLED`, a failed analysis, an errored task check). `2` on a usage error, and on a quota refusal, which prints `Launch quota exceeded:` with the server's sentence. A rate limit prints one line with the wait and exits 1; the SDK's watch loops wait it out on their own.