archal run

Run a scenario or inline task against digital twins and get a satisfaction score.

Usage

archal run [scenario] [options]

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

Arguments

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

Common options

These are the flags you’ll use most of the time. Run archal run --advanced to see the full set.

Inline --task runs still execute your configured agent. Use .archal.json to tell Archal how to start that process, then pair --task with --twin 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.
--twin <name>	Twin(s) for --task mode (repeatable or comma-separated)
--read-only	Force the generated --task scenario into the read-only (single-criterion) scaffold, bypassing the heuristic classifier. Only meaningful with --task.	false
--harness <path>	Path to a runnable headless harness (e.g. ./.archal/harness.ts). Omit to auto-discover a top-level harness.{ts,js,mjs,cjs}, or set agent in .archal.json.	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)
--reuse-session [session-id]	Reuse an active archal twin start session instead of provisioning a new one. Does not tear down the session at end.
--keep-state	Skip the scenario’s named-seed re-apply on a reused session. Alias: --no-reseed.	false
--fresh-seed	Force the scenario’s named seed to be re-applied on a reused session, wiping existing twin state first. Opposite of --keep-state.	false
-q, --quiet	Suppress non-error output	false
-v, --verbose	Enable debug logging	false

Advanced options

These are available but hidden from default --help output. Use archal run --advanced to see them.

Advanced flags are internal or back-compat (.hideHelp() in cli/src/commands/run.ts). They exist for debugging, CI integration, or legacy callers and can change or be removed without a deprecation window. Don’t script against them from a production CI path — prefer the Common options above.

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
--preflight-only	Validate config and exit without running	false
--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>	Attach run to a dashboard project
--proxy / --no-proxy	Force the TLS proxy on or off (on by default for local harness runs)	on
--allow-empty-state	Let a run proceed when the reused-session state probe fails. Debug-only.	false
--sandbox	Run agent in sandboxed container with TLS proxy	false

Examples

# Run with .archal.json in the current directory
archal run

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

# Run a single scenario
archal run scenario.md

# Three ways to supply the runnable agent path:

# 1. Explicit --harness flag
archal run --task "Create an issue titled 'hello'" --harness ./.archal/harness.ts --twin github

# 2. Repo-local auto-discovery — with a top-level harness.ts in the repo,
#    no --harness flag needed.
#    Note: a file at `.archal/harness.ts` is NOT auto-discovered — pass --harness explicitly.
archal run --task "Create an issue titled 'hello'" --twin github

# 3. .archal.json with { "agent": { "command": "npx", "args": ["tsx", "./.archal/harness.ts"] } } — the agent field
#    can point anywhere, including `.archal/harness.ts`.
archal run --task "Create an issue titled 'hello'" --twin github

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

# JSON output for CI
archal run scenario.md -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

These are set automatically for your agent process (see Test your agent for the full list):

Variable	Description
ARCHAL_ENGINE_TASK	The task or scenario prompt
ARCHAL_<TWIN>_URL	MCP endpoint per twin
ARCHAL_<TWIN>_BASE_URL	REST base URL per twin

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. It is not required to save traces locally.

Related

• Test your agent
• Writing scenarios
• CI integration
• Twin sessions