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

# archal run

> Run a scenario or inline task against hosted clones with Docker or sandbox mode. Score agent behavior across multiple runs and timeouts.

## Usage

```bash theme={null}
archal run [scenario] [options]
```

If you omit the scenario argument, Archal looks for `.archal.json` in the current directory.

Scored clone runs need a controlled runtime:

* Use `--docker` to build and run a repo-local harness directory.
* Use `--sandbox` for sandbox mode.

## Arguments

| Argument     | Description                                                                  |
| ------------ | ---------------------------------------------------------------------------- |
| `[scenario]` | Path to a scenario `.md` file. Optional if using `--task` or `.archal.json`. |

## Common options

These are the flags most runs need.

Inline `--task` runs still execute your configured `agent`. Use `.archal.json`
to tell Archal how to start that process, then pair `--task` with `--clone`
when you want a one-off smoke test without writing a scenario file first.

| Flag                      | Description                                                                       | Default                |
| ------------------------- | --------------------------------------------------------------------------------- | ---------------------- |
| `-c, --config <path>`     | Path to `.archal.json` config file                                                | auto-discovered in cwd |
| `--task <description>`    | Run an inline task instead of a scenario file. Still needs a runnable agent path. |                        |
| `--clone <name>`          | Clone(s) for `--task` mode (repeatable or comma-separated)                        |                        |
| `--harness <path>`        | Runnable harness path, such as `.` or `./.archal/harness.ts`                      | auto-discovered        |
| `-n, --runs <count>`      | Number of runs                                                                    | `1`                    |
| `-t, --timeout <seconds>` | Timeout per run in seconds                                                        | `180`                  |
| `-o, --output <format>`   | Output format: `terminal`, `json`                                                 | `terminal`             |
| `--seed <name-or-path>`   | Seed name or file path (`.json` / `.sql`)                                         | from scenario config   |
| `--tag <tag>`             | Only run if scenario has this tag (exits 0 if no match)                           |                        |
| `-q, --quiet`             | Suppress non-error output                                                         | `false`                |
| `-v, --verbose`           | Enable debug logging                                                              | `false`                |

## Advanced options

These are available with `archal run --advanced`.

<Warning>
  Advanced flags are hidden from normal help because they are for debugging or CI plumbing. Prefer
  the Common options above for project docs and stable scripts.
</Warning>

| Flag                           | Description                                                                               | Default     |
| ------------------------------ | ----------------------------------------------------------------------------------------- | ----------- |
| `-m, --model <model>`          | Evaluator model for probabilistic criteria                                                | from config |
| `--pass-threshold <score>`     | Minimum passing satisfaction score (0-100)                                                | `0`         |
| `--api-key <key>`              | API key for the model provider                                                            | from env    |
| `--agent-model <model>`        | Agent model identifier                                                                    | from env    |
| `--rate-limit <count>`         | Max total requests before 429                                                             | unlimited   |
| `--no-failure-analysis`        | Skip LLM failure analysis on imperfect scores                                             | `false`     |
| `--run-project-id <id>`        | Associate run with a dashboard project                                                    |             |
| `--read-only`                  | Force an inline `--task` into the read-only scaffold                                      | `false`     |
| `--reuse-session [session-id]` | Reuse an active `archal clone start` session instead of provisioning a new one            |             |
| `--keep-state`                 | Skip named-seed re-apply on a reused session                                              | `false`     |
| `--fresh-seed`                 | Re-apply the scenario's named seed on a reused session, wiping existing clone state first | `false`     |
| `--docker`                     | Build and run a repo-local harness directory in Docker with TLS interception              | `false`     |
| `--sandbox`                    | Run agent in sandboxed container with TLS interception                                    | `false`     |

## Examples

```bash theme={null}
# Run with .archal.json in the current directory
archal run --docker

# Use a specific config file
archal run --config path/to/.archal.json --docker

# Run a single scenario
archal run scenario.md --docker

# Supply the runnable agent path
archal run --task "Create an issue titled 'hello'" --harness . --docker --clone github

# Run 5 times and require 80% satisfaction
archal run scenario.md --docker --runs 5 --pass-threshold 80

# JSON output for CI
archal run scenario.md --docker -o json -q
```

## Exit codes

| Code | Meaning                                                                         |
| ---- | ------------------------------------------------------------------------------- |
| `0`  | Run succeeded and score met `--pass-threshold` (or scenario skipped by `--tag`) |
| `1`  | Runtime error or satisfaction below threshold                                   |
| `2`  | Validation error (bad flags, missing scenario, invalid config)                  |

## Environment variables

These configure `archal run` itself:

| Variable                | Description                                           |
| ----------------------- | ----------------------------------------------------- |
| `ARCHAL_TOKEN`          | Auth token (alternative to `archal login`)            |
| `ARCHAL_ENGINE_API_KEY` | Optional Archal engine key; not passed to the harness |
| `ARCHAL_ENGINE_MODEL`   | Default agent model identifier                        |

These are set automatically for your agent process:

| Variable                                                       | Description                                                  |
| -------------------------------------------------------------- | ------------------------------------------------------------ |
| `AGENT_TASK`                                                   | The task or scenario prompt                                  |
| `NODE_EXTRA_CA_CERTS` / `SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE` | CA paths for runtimes that need explicit trust configuration |

## Local run artifacts

Every `archal run` also writes local artifacts under `.archal/cache/`:

* `.archal/cache/last-run.json`
* `.archal/cache/runs/*.json`

Use `--output json` when you want machine-readable stdout.

## Saved scenarios

`archal run` always uses the local files you pass via `--harness`, the scenario
path argument, or `.archal.json`. **It does not auto-save** them to your
workspace. To make a scenario reusable across projects, push it explicitly:

```bash theme={null}
archal scenario push ./scenarios/close-stale-issues.md
```

Your harness stays local. Point `archal run` at it with `--harness` or the
`agent` field in `.archal.json`.