Unified CLI runner for AI coding agents with normalized event streaming
npm install axrunAI agent runner CLI. Runs AI coding agents through a unified interface.
``bash`
npm install -g axrun
`bashRun a prompt with an agent
axrun --agent claude "Add error handling to auth.ts"
axrun -a codex "Fix the bug in main.ts"
axrun -a gemini "Refactor the utils module"
axrun -a opencode --provider anthropic "Add logging"
axrun -a copilot "Write tests"
Options
-a, --agent Agent to use (claude, codex, gemini, opencode, copilot)
-p, --prompt Prompt text (alternative to positional argument)
-m, --model Model to use (agent-specific)
--provider Provider for OpenCode: anthropic, openai, google (google = gemini models)
--allow Permission rules to allow (comma-separated)
--deny Permission rules to deny (comma-separated)
--sandbox Run axexec inside an external sandbox (Podman container via axsandbox; requires --sandbox-image)
--sandbox-image Sandbox image (must include axexec; required with --sandbox)
--sandbox-include Include host directory (repeatable, mounted read-only at /include/)
--sandbox-mount Bind mount mapping :[:ro|rw] (repeatable, default ro)
--sandbox-persist Keep sandbox container running after the run
--vault-credential Fetch credentials from vault (requires AXVAULT or AXVAULT_URL+AXVAULT_API_KEY)
--preserve-github-sha Keep GITHUB_SHA env var (Gemini excludes by default)
-f, --format Output format: jsonl, tsv (sandbox default: jsonl)
--raw-log Write raw agent JSONL output to file (use relative paths with --sandbox)
--debug Enable debug mode (logs unknown events)
--list-agents List available agents
-V, --version Show version number
--help Show help
Supported Agents
| Agent | Package | API Key Env Var |
| -------- | ------------------------- | --------------------- |
| claude | @anthropic-ai/claude-code | ANTHROPIC_API_KEY |
| codex | @openai/codex | OPENAI_API_KEY |
| gemini | @google/gemini-cli | GEMINI_API_KEY |
| opencode | opencode-ai | ANTHROPIC_API_KEY (†) |
| copilot | @github/copilot | GITHUB_TOKEN |
(†) OpenCode supports multiple providers. Use
to specify which provider to use (anthropic, openai, google).CI/CD Usage
$3
Fetch credentials from a centralized vault server:
`bash
axrun --agent claude --vault-credential ci-oauth-token "Review this PR"
`Required: Set
env var with vault URL and API key as JSON:`json
{ "url": "https://vault.example.com", "apiKey": "axv_sk_..." }
`See axvault for vault setup.
$3
For CI/CD pipelines without vault, credentials can be passed via environment variables:
bash
Export credentials locally (one-time setup)
axauth export --agent claude --output creds.json --no-passwordStore as repository secret (e.g., AX_CLAUDE_CREDENTIALS)
axrun auto-detects and installs credentials
axrun --agent claude --prompt "Review this PR"
`| Agent | Credential Env Var |
| -------- | ----------------------- |
| claude | AX_CLAUDE_CREDENTIALS |
| codex | AX_CODEX_CREDENTIALS |
| gemini | AX_GEMINI_CREDENTIALS |
| opencode | AX_OPENCODE_CREDENTIALS |
| copilot | AX_COPILOT_CREDENTIALS |
For Claude, you can also use
(generated via claude setup-token`).MIT