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

> Inspect, download, and act on single trials.

```bash theme={"dark"}
evolve trial <command> [options]
```

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

## trial show

```bash theme={"dark"}
evolve trial show <trial-id>
```

Show one trial in full detail: its status, reward, `tokens`, `spent` and `spent (judge)` rows, `gpu compute (est.)` on a GPU trial, the exception when it failed, and its latest analysis with the verdicts, the summary and the typed failure. An uploaded trial prints its provider as `ported` and its reported figures apart from the metered ones.

The run's own files are under [`trial files`](#trial-files); the platform's stored artifacts (session files, the verifier log) are SDK-only, `trials().files()` and `file()`.

## trial trace

```bash theme={"dark"}
evolve trial trace <trial-id> [options]
```

Print a trial's parsed trace, filtered server-side.

<ParamField path="--type" type="event-type">
  Only events of exactly this type. At most 100 characters.
</ParamField>

<ParamField path="--grep" type="pattern">
  Only events matching this case-insensitive regex over type and content. A plain string is a plain substring. At most 512 characters; an invalid pattern is refused by the server with `invalid_input`.
</ParamField>

<ParamField path="--tail" type="n">
  Only the last N matching events, 1 to 10000, then paged oldest first.
</ParamField>

<ParamField path="--cursor" type="seq">
  Resume after this sequence number. The filters compose with it.
</ParamField>

<ParamField path="-l, --limit" type="n" default="200">
  Events per page fetch, not a total: the command drains the filtered trace. Max 1000.
</ParamField>

```bash theme={"dark"}
evolve trial trace d1a10c4e-… --grep 'permission denied' --tail 50
```

## trial download

```bash theme={"dark"}
evolve trial download <trial-id> [options]
```

Save a trial as its trial tree plus `evolve.json`, or stream one artifact to stdout. The two modes are exclusive.

<ParamField path="-o, --output-dir" type="dir" default="trials/">
  Directory to save under. Files land in `<dir>/<trial-id>/`.
</ParamField>

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

<ParamField path="--stream" type="artifact">
  Print one artifact to stdout instead of saving: `trace-parsed`, `verifier`, `trace-stdout`, `trace-stderr`, `trace-atif` (the ATIF trajectory), `trajectory` (reserved: the harness-native session file), `agent-home`, or `filesystem` (the run's file system as one `.tar.gz`, raw bytes — pipe it to a file; the same archive as `trial files archive`).
</ParamField>

<ParamField path="--cursor" type="seq">
  With `--stream trace-parsed`: resume after this sequence number.
</ParamField>

<ParamField path="--limit" type="n">
  With `--stream trace-parsed`: max events per page.
</ParamField>

```bash theme={"dark"}
evolve trial download d1a10c4e-… --stream trace-stdout
```

## trial files

```bash theme={"dark"}
evolve trial files <status|ls|cat|search|changes|archive> <trial-id> [path] [options]
```

The run's file system: while the box runs, `files` reads it as it changes; after the run, the same commands read the kept tree. `files status` says which you get.

* `files status <trial-id>` — `live`, `captured`, `capturing` (the kept tree is still being written) or `none`; the box, how change events arrive (`watcher`), and the capture record (`ready`, `incomplete` with what was left out, or `failed`).
* `files ls <trial-id> [path]` — one folder, sorted by name (default `/`). Each row shows the type, mode, size, mtime and name; `created (agent)` or `modified (verifier)` marks what the run changed and when, `image only` marks a file the run never touched (it lists but does not open on the kept tree).
* `files cat <trial-id> <path>` — the raw bytes of one file, to stdout. `--range bytes=a-b` (or `bytes=a-`, `bytes=-n`) reads a slice.
* `files search <trial-id> <text>` — every line matching the text, as `path:line: snippet`. `--path` narrows the search to one folder (the whole box takes seconds); `--regex` treats the text as a pattern; a `(truncated)` note means there was more.
* `files changes <trial-id>` — the files the run created, modified or removed, with the phase (`--phase agent|verifier`).
* `files archive <trial-id>` — a `.tar.gz` of one subtree (`--path`, default the whole tree) to stdout, or saved under `-o <dir>`. The kept tree's archive lists the files it does not carry in `MANIFEST.tsv`; while the box runs, a subtree too large to read out in time is refused (`feature_unsupported`).

<ParamField path="--source" type="live|capture">
  Force the source. Without it, whichever the run has. A source that is not there is refused with `filesystem_state`.
</ParamField>

<ParamField path="-l, --limit" type="n">
  Page size on `ls`, `search` and `changes` (`ls`, `changes` default 500; `search` default 200; max 1000).
</ParamField>

<ParamField path="--cursor" type="c">
  Resume a paged `ls` or `changes` after the previous page's `next_cursor`.
</ParamField>

```bash theme={"dark"}
evolve trial files ls d1a10c4e-… /app/work
evolve trial files search d1a10c4e-… 'permission denied' --path /app/work
evolve trial files archive d1a10c4e-… --path /app/work -o archives/
```

## trial logs

```bash theme={"dark"}
evolve trial logs <trial-id> --stream <name> [--follow] [options]
```

The box's own streams: `agent` (the harness's stdout and stderr), `verifier` and `system` (the box's system log, only when the job asked for it with `--system-log`); `setup` and `metrics` are named but not recorded today, so their pages are empty and say why. One page by default; `--follow` keeps printing lines as they arrive while the box lives, and returns once it is gone.

<ParamField path="--stream" type="name" required>
  `agent`, `verifier`, `system`, `setup` or `metrics`.
</ParamField>

<ParamField path="-f, --follow">
  Keep printing new lines while the box lives.
</ParamField>

<ParamField path="-l, --limit" type="n" default="1000">
  Lines per page, max 1000.
</ParamField>

<ParamField path="--cursor" type="seq">
  Resume after this line.
</ParamField>

```bash theme={"dark"}
evolve trial logs d1a10c4e-… --stream agent --follow
```

## trial procs

```bash theme={"dark"}
evolve trial procs <trial-id>
```

The processes running in the box right now. Live only: once the box is gone the command is refused with `filesystem_state`.

## trial retry

```bash theme={"dark"}
evolve trial retry <trial-id>
```

Run one settled trial again. The result is a job.

## trial regrade

```bash theme={"dark"}
evolve trial regrade <trial-id>
```

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

## trial stop

```bash theme={"dark"}
evolve trial stop <trial-id> [trial-id...]
```

Stop in-flight trials without cancelling their job.

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