Skip to main content
archal preprod is the CLI surface for pre-production autonomous checks. It can inspect a repo, author starter scenario files, run scenarios, classify failures, optionally execute a coding-agent fix command, rerun, validate, and publish a draft PR after validation passes.

​
Commands

archal preprod plan [options]
archal preprod run [scenarios...] [options]
Use plan for setup and authoring. Use run for the bounded loop.

​
archal preprod plan

archal preprod plan --repo . --write-scenarios --write-config --out .archal/preprod-plan.json
OptionDescription
--repo <path>Repo path to inspect. Defaults to the current directory
--out <path>Write the JSON plan to a file
--write-scenarios [dir]Write parser-validated authored scenario markdown files. Defaults to archal
--write-configWrite a minimal .archal.json from the generated config spec when no config exists
--jsonPrint machine-readable JSON
Generated scenarios are written under archal/ by default. The command refuses to overwrite existing scenario files or .archal.json.

​
archal preprod run

archal preprod run [scenarios...] [options]
Omit scenario paths to use .archal.json.
OptionDefaultDescription
--planResolve scenarios and print the loop plan without running them
--dry-runRun and classify scenarios, then stop before fix or PR commands
--artifacts <dir>Write redacted result and failure-classification artifacts
--max-fix-attempts <count>2Maximum coding-agent fix attempts, between 0 and 10
--allow-external-executionAllow --fix-command and --pr-command to execute local processes
--fix-command <command>Coding-agent fix command. Receives ARCHAL_PREPROD_FAILURES_JSON and ARCHAL_PREPROD_ATTEMPT
--validation-command <command>Additional local validation command required before PR creation
--open-prOpen a PR after scenario reruns and validation pass
--pr-command <command>PR publishing command. Receives ARCHAL_PREPROD_VALIDATION_JSON
--jsonEmit machine-readable output
Scenario options mirror archal run:
OptionDescription
-c, --config <path>Path to .archal.json
--workspace-scenario <id-or-slug>Run a scenario saved on the active workspace
--task <description>Run an inline task without a scenario file
--clone <name>Clone or clones for --task
-n, --runs <count>Number of runs for each scenario
-t, --timeout <seconds>Timeout per run in seconds
--pass-threshold <score>Required satisfaction score before validation. Default: 80
--model <model>Evaluator model
--agent-model <model>Agent model, or none for deterministic harnesses
--harness <path>Path to a runnable harness
--workspace <name-or-id>Use an Archal workspace by name or id
--sandboxRun the harness in the sandbox engine
--dockerRun the harness in Docker interception mode
--no-dockerDisable Docker interception mode
--allow-low-fidelity-networkingAllow explicit low-fidelity local debug networking
--seed <name-or-path>Seed name or local seed file
--reuse-session [session-id]Reuse an existing clone session
--keep-statePreserve state in a reused session
--fresh-seedForce re-apply of the scenario seed

​
Examples

Resolve the loop without running anything: 
archal preprod run --plan --artifacts .archal/preprod
Classify failures without allowing a local fix command: 
archal preprod run archal/github-pr-safety.md \
  --runs 3 \
  --dry-run \
  --artifacts .archal/preprod
Run a bounded patch, rerun, validate, and draft-PR loop: 
archal preprod run archal/github-pr-safety.md \
  --runs 3 \
  --pass-threshold 80 \
  --max-fix-attempts 2 \
  --allow-external-execution \
  --fix-command 'codex exec "Fix the failures described in $ARCHAL_PREPROD_FAILURES_JSON"' \
  --validation-command 'pnpm test' \
  --open-pr \
  --pr-command 'gh pr create --draft --fill' \
  --artifacts .archal/preprod
Run every scenario listed in .archal.json and stop after classification: 
archal preprod run --dry-run --artifacts .archal/preprod

​
Output statuses

StatusMeaning
passedscenarios passed, validation passed, and PR publishing was either not requested or completed
planned--plan resolved scenarios and stopped
dry_run--dry-run classified failures and stopped before fix commands
blockedthe loop stopped before a safe next phase
budget_exhaustedfix attempts reached --max-fix-attempts
validation_failedscenario reruns passed, but --validation-command failed
pr_failedvalidation passed, but the PR command or PR verification failed
Common stop reasons include no_scenarios, external_execution_disabled, blocking_failure_classification, fix_budget_exhausted, validation_command_failed, and pr_command_failed.

​
Artifacts

Set --artifacts <dir> to write:
FileContents
preprod-result.jsonRedacted loop result with status, stop reason, attempts, scenario run ids, validation, PR summary, and artifact metadata
preprod-failures.jsonSchema-limited failure classifications for a coding agent or handoff
Failure classifications map to harness setup, routing, clone fidelity, scenario/evaluator, agent behavior, and unknown failure categories.

​
Coding-agent hooks

Fix and PR commands execute through /bin/sh -lc with a restricted environment. The fix command receives:
VariableContents
ARCHAL_PREPROD_FAILURES_JSONSchema-limited failure payload with scenario paths, classifications, and digests
ARCHAL_PREPROD_ATTEMPTOne-based fix attempt number
ARCHAL_PREPROD_USAGE_PATHOptional path where the command can write token/cost usage JSON
The PR command receives ARCHAL_PREPROD_VALIDATION_JSON after scenario reruns and the validation command pass. It should print the GitHub PR URL. By default Archal expects a draft PR; set ARCHAL_PREPROD_ALLOW_READY_PR=true only when a ready-for-review PR is intentional.

​
Safety

  • --plan never runs scenarios.
  • --dry-run runs and classifies scenarios, but does not invoke fix or PR commands.
  • Fix and PR commands do not run unless --allow-external-execution is set.
  • PR publishing only runs when --open-pr and --pr-command are provided.
  • PR verification checks the head commit, changed file count, draft status, and GitHub checks before reporting success.

​
See also