Usage
archal run [scenario] [options]
.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 / .md) | 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.
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.
| 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 |
--seed-cache | Reuse cached dynamic seeds | false |
--clear-seed-cache | Clear cached seeds before running | false |
--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. Alias: --no-reseed | false |
--fresh-seed | Re-apply the scenario’s named seed on a reused session, wiping existing clone state first | false |
--allow-empty-state | Let a run proceed when the reused-session state probe fails. Debug-only. | 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
# 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 | API key for the model under test |
ARCHAL_ENGINE_MODEL | Default agent model identifier |
| 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 harnesses and 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 harness or scenario reusable across projects, save it
explicitly:
archal harness create "My agent" --harness ./.archal/harness.ts
archal scenario push ./scenarios/close-stale-issues.md
archal run uses a custom harness that is not saved to the active
workspace, it prints a one-line tip on stderr. Pass --quiet to suppress the
tip.