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

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli version 0.1.4, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli@0.1.4` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# ancha runs

> Send a finished run to your workspace with ancha runs upload, and list, show and start the playground runs a workspace holds.

`ancha runs` works with the runs your workspace holds: the results you upload from this computer, and the playground runs the workspace runs itself. Every subcommand takes `--json`, and every object it prints names its `workspace`.

## ancha runs upload

```bash theme={null}
ancha runs upload [options] <run>
```

| Argument | Description |
| - | - |
| `run` | A finished run: its id (run\_…) or "latest" |

| Option | Description |
| - | - |
| `--out <dir>` | Where run directories are (default: .ancha/runs) |

Sends a run that already finished on this computer to your workspace, where the console shows it. Use it when a run was made without `--upload`, when an upload failed, or after the fact in CI.

```bash theme={null}
ancha runs upload latest
```

```text Output theme={null}
uploaded: https://app.ancha.io/runs/run_20261031-103205_6148f5000f42139f
```

With `--json`, the result is `{"runId", "workspace", "upload": {"url", "bytes", "files", "replaced"}}`. Uploading a run again replaces its copy in the workspace, and `replaced` is `true`. It needs a workspace: `ancha login`, or `ANCHA_SERVER_URL` and `ANCHA_API_KEY`. Without one it exits `2` with `--upload needs a workspace`. See [Results in your workspace](https://docs.ancha.io/cloud/results.md) for what the upload holds.

## ancha runs list

```bash theme={null}
ancha runs list [options]
```

| Option | Description |
| - | - |
| `--agent <id>` | Only this agent's runs |

Lists the workspace's playground runs, newest first, with their status, grade and queue position.

## ancha runs show

```bash theme={null}
ancha runs show <id>
```

| Argument | Description |
| - | - |
| `id` | A run: play\_… (a playground run) or run\_… / "latest" (a run on this computer) |

Shows one run with its attempts and grade. A `run_…` ID or `latest` reads a run on this computer. `ancha attempt show <run> <attempt>` prints one attempt's response, calls and final tool data.

## ancha runs start

```bash theme={null}
ancha runs start [options]
```

| Option | Description |
| - | - |
| `--agent <id>` | The saved agent |
| `--test <file>` | The test or scene file; it must give the agent a task |
| `--world <id-or-name>` | Saved world to run in (default: the test's world) |
| `-n, --attempts <n>` | Attempts (default: the test's attempts, else 1) |
| `--concurrency <n>` | Attempts at once (default: "1") |
| `--idempotency-key <key>` | Retry safely: the same key and definition return the original run |
| `--commit <sha>` | The git commit of the code this run tests (ancha run --on cloud sets it; here, the folder's own) |
| `--dirty` | That code had uncommitted changes |
| `--no-wait` | Return once the run is accepted (hosted workspace only) |

Runs one test with a saved agent in fresh worlds. In a hosted workspace the console runs it, so a dropped connection does not stop it; `ancha runs show <id>` picks it up. Running your own agent in the workspace is in private beta: until your workspace has access, the command is refused with `hosted runs of your own agent are in private beta for this workspace`. With `--local`, the run happens on this computer with the project's own agents and worlds, and `--no-wait` is a usage error.

## Where the commands run

With a hosted workspace, from `ancha login` or `ANCHA_SERVER_URL`, `ancha runs list`, `show` and `start` work on that workspace's runs, the same ones the console shows. `--local` keeps them on this project's `.ancha/`. `ancha runs upload` always sends to the workspace.

## Exit codes

`0`. `2` for an unknown run, a test without a task, no workspace for `upload`, or `--no-wait` without a hosted workspace. `3` when the workspace cannot be reached or does not answer the upload; `ancha runs upload <run id>` tries again.


## Related topics

- [ancha run](https://docs.ancha.io/cli/run.md)
- [Attempts and runs](https://docs.ancha.io/concepts/attempts-and-runs.md)
- [ancha logs](https://docs.ancha.io/cli/logs.md)
- [ancha wait](https://docs.ancha.io/cli/wait.md)
- [ancha report](https://docs.ancha.io/cli/report.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.