@archal/cli

The Archal CLI — test AI agents against digital twins.

Archal provisions hosted twin sessions, runs your scenario through a configurable engine (API or local harness), and evaluates outcomes against deterministic and probabilistic criteria.

Install

npm install -g @archal/cli

Quick Start

# Authenticate with Archal
archal login
# or: export ARCHAL_TOKEN=archal_...

# Run a scenario with a bundled harness
archal run scenario.md --harness react

Commands

| Command | Description | | --- | --- | | archal login | Authenticate via browser auth or token | | archal logout | Log out and remove credentials | | archal run | Run scenarios from .archal.json config | | archal scenario list | Browse local scenarios | | archal twin | Manage hosted twin sessions | | archal trace | View recent scenario traces | | archal usage | Check session minutes and plan |

Environment Variables

| Variable | Description | | --- | --- | | ARCHAL_TOKEN | Auth token for the Archal backend API | | ARCHAL_AUTH_URL | Optional auth endpoint override for browser login and /auth/* calls | | ARCHAL_API_URL | Optional /api/* endpoint override (falls back to ARCHAL_AUTH_URL/hosted default) | | ARCHAL_STRICT_ENDPOINTS | Set to 1 to require explicit ARCHAL_AUTH_URL/ARCHAL_API_URL and disable hosted fallback | | ARCHAL_TELEMETRY_URL | Optional telemetry ingest endpoint override | | ARCHAL_ENGINE_ENDPOINT | Default API engine endpoint | | ARCHAL_ENGINE_TOKEN | Default API engine auth token | | ARCHAL_ENGINE_MODEL | Default engine model identifier | | ARCHAL_ENGINE_TIMEOUT | Default API engine timeout in seconds | | ARCHAL_ENGINE_TWIN_URLS | Default path to remote twin URL overrides | | ARCHAL_DEFAULT_HARNESS | Default harness name, local harness file, or local harness directory | | OPENCLAW_URL | Legacy OpenClaw gateway URL alias for API mode | | OPENCLAW_GATEWAY_TOKEN | Legacy OpenClaw gateway token | | OPENCLAW_GATEWAY_PASSWORD | Legacy password-mode OpenClaw gateway auth value | | OPENCLAW_AGENT_ID | Legacy OpenClaw agent/model id (prefer ARCHAL_ENGINE_MODEL) |

Documentation

For full documentation, architecture details, and contributor guides, see the Archal monorepo on GitHub.

License

MIT