Skip to main content

​
Usage

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

​
Arguments

ArgumentDescription
[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.
FlagDescriptionDefault
-c, --config <path>Path to .archal.json config fileauto-discovered in cwd
--task <description>Run an inline task instead of a scenario file
--twin <name>Twin(s) for --task mode (repeatable or comma-separated)
-n, --runs <count>Number of runs1
-t, --timeout <seconds>Timeout per run in seconds180
--seed <name>Override twin seedfrom scenario config
--tag <tag>Only run if scenario has this tag (exits 0 if no match)
--proxyRoute agent HTTP traffic through TLS proxy to twinsfalse
-q, --quietSuppress non-error outputfalse
-v, --verboseEnable debug loggingfalse

​
Advanced options

These are available but hidden from default --help output. Use archal run --advanced to see them.
FlagDescriptionDefault
-o, --output <format>Output format: terminal, jsonterminal
-m, --model <model>Evaluator model for probabilistic criteriafrom config
--pass-threshold <score>Minimum passing satisfaction score (0-100)0
--api-key <key>API key for the model providerfrom env
--agent-model <model>Agent model identifierfrom env
--engine-endpoint <url>Remote agent gateway URLfrom ARCHAL_ENGINE_ENDPOINT
--engine-token <token>Bearer token for engine authfrom ARCHAL_ENGINE_TOKEN
--rate-limit <count>Max total requests before 429unlimited
--preflight-onlyValidate config and exit without runningfalse
--seed-cacheReuse cached dynamic seedsfalse
--clear-seed-cacheClear cached seeds before runningfalse
--no-failure-analysisSkip LLM failure analysis on imperfect scoresfalse
--run-project-id <id>Attach run to a dashboard project
--sandboxRun agent in sandboxed container with TLS proxyfalse

​
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

# Inline task against a specific twin
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

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

​
Environment variables

These configure archal run itself:
VariableDescription
ARCHAL_TOKENAuth token (alternative to archal login)
ARCHAL_ENGINE_API_KEYAPI key for the model under test
ARCHAL_ENGINE_ENDPOINTRemote agent gateway URL
ARCHAL_ENGINE_TOKENAuth token for remote engine
ARCHAL_ENGINE_MODELDefault agent model identifier
These are set automatically for your agent process (see Test your agent for the full list):
VariableDescription
ARCHAL_ENGINE_TASKThe task or scenario prompt
ARCHAL_<TWIN>_URLMCP endpoint per twin
ARCHAL_<TWIN>_BASE_URLREST base URL per twin