CLI Reference

Installation

            Terminal
          
            npm install -D replayci
npx replayci [command] [options]

Commands

`replayci` (default)

Run contracts against a provider. Reads config from .replayci.yml, overridden by CLI flags.

            Terminal
          
            npx replayci
npx replayci --provider openai --model gpt-4o-mini
npx replayci --pack packs/my-pack --persist

`replayci init`

Scaffold a new project with a config file and starter pack. Skips files that already exist.

`replayci help`

Show help text. Also available as --help or -h.

`replayci drift`

Run drift detection against the current baseline.

`replayci export-bundle`

Export a replay bundle for offline verification.

`replayci replay-bundle`

Replay a previously exported bundle.

Options

Provider & model

Flag	Description	Default
`--provider <name>`	LLM provider: `openai`, `anthropic`, `recorded`	From config
`--model <name>`	Model ID (e.g. `gpt-4o-mini`)	From config
`--pack <path>`	Path to contract pack directory	`packs/starter`

Execution

Flag	Description	Default
`--persist`	Write run artifacts to disk	`false`
`--repeat <n>`	Run N times for determinism proof	`1`
`--only_contracts <csv>`	Filter to specific contract filenames	All
`--json`	Force JSON output (default for non-TTY)	Auto-detect

Identity

Flag	Description	Default
`--tenant_id <id>`	Tenant identifier	`t_default`
`--run_mode <mode>`	Run mode: `manual`, `scheduled`, `ci`	`manual`

Timeouts & limits

Flag	Description	Default
`--timeout_ms <ms>`	Timeout per contract in milliseconds	`30000`
`--retry_cap <n>`	Maximum retry attempts	`2`
`--max_contracts <n>`	Limit number of contracts to run	All

Shadow mode

Flag	Description
`--shadow-capture`	Enable shadow capture for live provider runs
`--shadow-provider <name>`	Shadow provider for comparison
`--shadow-model <name>`	Shadow model for comparison

Environment variables

Variable	Description	Required
`REPLAYCI_API_KEY`	API key for pushing results to the dashboard	For dashboard push
`REPLAYCI_PROVIDER_KEY`	Provider API key (OpenAI or Anthropic)	For live provider runs
`REPLAYCI_API_URL`	Override API base URL	No
`DATABASE_URL`	PostgreSQL connection string	For local DB persistence

API keys always come from environment variables — never from .replayci.yml or CLI flags.

Config file

ReplayCI reads .replayci.yml from the project root. CLI flags override config values.

            .replayci.yml
          

            pack: "./packs/starter"
provider: openai
model: gpt-4o-mini
persist: false
tenant_id: t_default
run_mode: manual
          

Resolution order: CLI flags > .replayci.yml > built-in defaults.

Output formats

Pretty (default for TTY)

  replayci · openai/gpt-4o-mini · 4 contracts

  ✓ tool_call              Pass  a3f82c91
  ✓ function_call          Pass  b7d104e3
  ✓ structured_output      Pass  c9a2f156
  ✗ error_handling         Fail  e1b3d478  ← schema_payload

  3/4 passed · 1 failed

  results → https://app.replayci.com/runs/r_8f3a2c

JSON (default for pipes/CI)

            Terminal
          
            npx replayci --json | jq '.provider_run.steps[0].state'

Dashboard push

When REPLAYCI_API_KEY is set and a provider run completes, results are automatically pushed to the hosted dashboard.

Push is independent of --persist — both can run simultaneously
Push failure warns to stderr but does not affect the exit code
Override the API URL with REPLAYCI_API_URL for local development

Determinism proof

            Terminal
          
            npx replayci --repeat 3

Output includes a determinism_proof object showing whether each step produced identical fingerprints across all runs.

Exit codes

Code	Meaning
`0`	All contracts passed
`1`	One or more contracts failed, or a runtime error occurred
`2`	Drift detection or unknown-rate gate failure

Examples

            Terminal
          

            # Initialize a new project
npx replayci init

# Run with defaults from .replayci.yml
npx replayci

# Run against OpenAI with a specific model
npx replayci --provider openai --model gpt-4o-mini

# Run against Anthropic
npx replayci --provider anthropic --model claude-sonnet-4-6

# Run against recorded fixtures (offline, deterministic)
npx replayci --provider recorded

# Run specific contracts only
npx replayci --only_contracts tool_call.yaml,function_call.yaml

# Prove determinism with 3 identical runs
npx replayci --repeat 3

# Force JSON output for CI
npx replayci --json

# Shadow comparison: OpenAI primary, Anthropic shadow
npx replayci --provider openai --model gpt-4o-mini \
  --shadow-capture --shadow-provider anthropic --shadow-model claude-sonnet-4-6

# Show help
npx replayci --help
          