archal run

Usage

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.

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

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

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.

CLI

SDK

API reference

Clones

Usage

Arguments

Common options

Advanced options

Examples

Exit codes

Environment variables

Local run artifacts

Saved scenarios

​Usage

​Arguments

​Common options

​Advanced options

​Examples

​Exit codes

​Environment variables

​Local run artifacts

​Saved scenarios

Usage

Arguments

Common options

Advanced options

Examples

Exit codes

Environment variables

Local run artifacts

Saved scenarios