Skip to main content

​
Usage

archal demo --model <model> [options]
Runs your chosen model through all bundled harnesses on a selected scenario, producing a side-by-side comparison table. Demonstrates how agent architecture affects satisfaction scores — the same model produces different results depending on the harness.

​
Options

FlagDescriptionDefault
-m, --model <model>(required) Model to test (e.g. gemini-2.5-flash, claude-sonnet-4-20250514)—
--api-key <key>API key for the model provider (overrides env vars)from env
--scenario <id>Skip interactive picker, use this scenario by name/idinteractive
-n, --runs <count>Runs per harness1
-t, --timeout <seconds>Timeout per run in seconds120
-q, --quietSuppress non-error outputfalse
-v, --verboseEnable debug loggingfalse
--jsonOutput results as JSONfalse

​
How it works

  1. Authenticates with Archal (cloud twins require login)
  2. Detects the provider from your model name (Gemini, Anthropic, OpenAI)
  3. Resolves the API key from --api-key, ARCHAL_ENGINE_API_KEY, or provider-specific env vars (GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY)
  4. Presents an interactive scenario picker (or uses --scenario to skip)
  5. Runs the scenario through each bundled harness sequentially
  6. Prints a comparison table with satisfaction scores
The interactive scenario picker requires a TTY. In non-interactive environments (CI, piped input), pass --scenario <name> to select directly.

​
Example

archal demo --model gemini-2.5-flash

  Archal Demo
  Model: gemini-2.5-flash (Gemini)
  API Key: ***aBcD (GEMINI_API_KEY)

  ? Select a scenario:
    GitHub
      1. Close Stale Issues (easy)
    Slack
      2. Summarize Channel (easy)

  Running "Close Stale Issues" through 4 harnesses...

  ┌─────────────┬──────────────┬────────────────────────────┐
  │ Harness     │ Satisfaction │ Notes                      │
  ├─────────────┼──────────────┼────────────────────────────┤
  │ balanced    │ 95.0%        │ ★ Recommended              │
  │ guarded     │ 90.0%        │                            │
  │ prompt-only │ 72.0%        │                            │
  │ baseline    │ 30.0%        │ ⚠ Baseline only            │
  └─────────────┴──────────────┴────────────────────────────┘

​
API key resolution

The demo command resolves the engine API key in this order:
  1. --api-key flag
  2. ARCHAL_ENGINE_API_KEY environment variable
  3. Provider-specific env vars: GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY
Persist keys in your shell profile or CI secret manager (not in CLI config).