ax run

Two id shapes appear below: a run request id covers one ax experiment run submission, and a composite run id (<variant_id>::<hash>) names one run inside it. Platform-backed commands also accept --org <org-id>, and all but run cancel and run cleanup accept --json; neither flag is repeated in the tables. Arguments marked required must be supplied; everything else is optional, and flags combine freely unless a row says otherwise.

run list

List runs, one row per run, grouped by status and newest first.

ax run list

When the number of runs returned equals --limit, a warning on stderr says that more matching runs may exist. This applies to both the default and any explicit limit. Increase --limit to fetch more, or narrow the filters at the maximum of 500.

--json keeps stdout valid JSON and adds list_metadata.runs with count_scope, returned_count, limit, and limit_reached, plus a warnings array. limit_reached: true signals a possible incomplete list; it does not prove that more runs exist.

That classification lands minutes after a run finishes, so --agent-test-aware never matches a run that is still unclassified, and there is no filter for the opposite verdict. Seeing a classification does not require the flag: whenever any listed run carries one, the table gains a trailing AGENT TEST AWARENESS column, and piped output gains three matching columns. --json rows always carry test_aware, behavior_changed, and awareness_cause, each null until the run is classified.

Examples:

# Errored runs for one experiment
ax run list --experiment my-experiment --status errored

# Completed runs, grouped by variant
ax run list --status completed --group-by variant

run view

View a run request roll-up, or one run in detail with its tests, conversation, or setup log.

ax run view <RUN_REQUEST_ID | RUN_ID>

Transcript output adapts to stdout. An interactive terminal shows the run summary and a table. A pipe receives headerless TSV in seq, ts, role, kind, origin, text order, with the run summary and completeness notices on stderr. Pass --json for one structured run document with transcript.turns.

A user turn's origin says who wrote it: human for the prompt a person wrote, harness for context the coding agent's software inserted, such as an environment summary or a system reminder. Assistant and reasoning turns have no origin (empty in TSV, null in JSON), and neither does a user turn from a run whose session data records none.

The tool calls row counts failed calls and lists them beneath it as #<position> <tool>: <error excerpt>, where the position is the call's order among all of the run's tool calls and the excerpt is cut to 160 characters. Ten calls are listed, then a +N more line, or + more not shown when the platform cut its list and the total is unknown. If the platform cannot read the details, the row says failed call details unavailable. With --json, the run carries failed_tool_calls (up to 50, each with seq, position, tool_name, failed, error_text, error_truncated, error_chars) and failed_tool_calls_truncated. When the list is cut, ax run query <RUN_ID> sql "SELECT seq, tool_name, payload FROM tool_interactions WHERE is_error ORDER BY seq" --limit 10000 returns every failed call. In a transcript, each listed failed call is also a tool turn of kind tool_error; its JSON turn carries the same object as tool_call (null on other turns), and the text cell reads <tool>: <error text>. error_text is the failed call's joined error content with likely secrets redacted (shown as [redacted]), cut to at most 2,000 Unicode code points; error_truncated is true when the redacted text was cut, and error_chars is the length in Unicode code points of the redacted error text, before the cut.

Run status and test outcome are separate signals: a run whose agent finished but whose tests failed is still completed (with a non-green tests line); only infrastructure failures are errored. For request roll-ups the command exits non-zero when any run ended unsuccessfully (setup failure, timeout, cancel); test failures alone do not change the exit code.

A run that ran out of time is reported as such rather than as a bare exit reason. The detail cell reads timed out at 600s · Basic plan limit, the platform's explanation of the limit prints below the failures it accounts for, and a Next: line gives the single action worth taking (upgrade, raise limits.max_time_seconds to a stated value and rerun). With --json, each run carries time_limit (budget_seconds, plan_cap_seconds, hit, or null when no budget was recorded) and a guidance array; a request roll-up adds top-level timed_out_count, plan_limited_count, and guidance. ax run list --json carries time_limit per row, so you can find the affected runs and then call ax run view on one for the explanation. See Cloud run time limits.

--setup-log prints the run's setup.log on stdout, followed by a Setup checks summary: each check's pass or fail, name, exit code, duration, and YAML location, plus the stderr tail of any failed check. Logs over 256 KiB show only the last 256 KiB, with a truncation notice on stderr. A run with no recorded setup log prints No setup log recorded for run <RUN_ID> and exits 0. With --json, the run returns scope, run_id, found, content, truncated, total_size_bytes, max_bytes, and a setup_checks array whose entries add stdout_tail and stderr_tail.

When a run contains evidence that the agent is aware it is being tested, it is classified as "test aware" and an agent test awareness row appears with the cause and evidence excerpts. Unclassified runs, and runs where the agent did not notice, look unchanged.

Examples:

# Roll-up for a whole submission
ax run view 01KSDQ...

# One run's failing test, with output
ax run view 'claude::p0::abc123' --test report-exists

# One run's dialogue as structured output
ax run view 'claude::p0::abc123' --transcript --json

# Dialogue and reasoning with a raised turn limit
ax run view 'claude::p0::abc123' --transcript --include reasoning --limit 1000

# Setup output and setup-check results for one run
ax run view 'claude::p0::abc123' --setup-log

run watch

Poll a run request until it reaches a terminal status.

ax run watch <RUN_REQUEST_ID>

run query

Run read-only SQL against platform data, scoped to one run. Platform test scripts use the separate test-only ax-run-query command; authentication is supplied automatically and limited to that run.

ax run query <RUN_ID> sql "SELECT * FROM test_analysis"

Examples:

# What is queryable
ax run query 'claude::p0::abc123' sql --tables

# Failing tests for one run
ax run query 'claude::p0::abc123' sql \
  "SELECT test_name, exit_code FROM test_analysis WHERE exit_code != 0" --format table

# Conversational evidence inside a platform test (stdout and/or transcript)
ax-run-query "$AX_RUN_ID" sql \
  "SELECT count() AS matches FROM events WHERE source IN ('stdout', 'transcript')"

See Tests for a complete transcript assertion.

run rerun

Rerun failed or canceled variants from a prior platform request, or re-run tests only against completed runs with --tests (see Tests).

ax run rerun <RUN_REQUEST_ID>
ax run rerun <RUN_ID> --tests --experiment experiment.yaml

Test-only reruns execute against each run's captured sandbox snapshot; if the snapshot was garbage-collected or never captured, the submit is rejected and you should create new runs instead. Tests that query transcript events with $AX_RUN_ID receive the same run-scoped access during a retest. User-triggered test-only reruns do not run the environment's teardown again.

run cancel

Cancel all jobs in a run request, or selected runs within it.

ax run cancel <RUN_REQUEST_ID>

run cleanup

Run a previously skipped or failed declared teardown for one platform run.

ax run cleanup <RUN_ID>

Create a retained platform run with ax experiment run <EXPERIMENT> --no-teardown. When that run finishes, the CLI prints its exact cleanup command. Cleanup runs the declared teardown only. It does not repeat setup, agent execution, or tests, and exits non-zero if teardown fails.