AIX CLI Command Reference
This document provides complete syntax, arguments, options, and exit code definitions for the aix CLI binary.
1. Top-Level Command Syntax
aix [OPTIONS] [PROMPT]
aix [COMMAND] [ARGS...]Global Options
| Option | Shorthand | Type | Description |
|---|---|---|---|
--mode | -m | control|auto|fast|plan | Execution autonomy mode (Default: control) |
--yes | -y | flag | Auto-approve bounded tool executions (Identical to --mode auto) |
--plan | flag | Dry-run mode: generates diff plan without writing to filesystem | |
--target | -t | sn|gcp|local | Environment endpoint target profile (Default: sn) |
--model | string | Override default model (e.g. claude-3-5-sonnet, qwen-max-longcontext) | |
--timeout | integer | Maximum execution timeout in seconds (Default: 600) | |
--verbose | -v | flag | Enable detailed debug logs, JSON-RPC payloads, and timing |
--version | -V | flag | Display version information and exit |
--help | -h | flag | Show help screen and command options |
2. Command Reference
aix run / Direct Prompt Execution
Execute autonomous engineering workflows directly:
# Interactive single prompt
aix "Refactor the payment retry loop in payments/worker.py to use exponential backoff"
# Fully automated non-interactive SWE loop
aix -y "Fix issue #412: WMS GC stock adjustment event dropped on network timeout"
# Stream execution output in JSONL format for CI/CD runners
aix --mode auto --output jsonl "Run static security audit"aix doctor
Audit environment, credentials, network routes, and sandbox permissions:
aix doctor [--fix] [--json]aix profile
Manage corporate environment connections:
aix profile list # List all configured profiles
aix profile show # Display active profile details
aix profile use <name> # Switch active profile (e.g. sn, gcp)
aix profile add <name> # Add new connection targetaix tui
Launch the 4-Split interactive full-screen terminal dashboard:
aix tui [--session <session_id>]aix vibe (Multi-Agent Swarm Orchestration)
Orchestrate a team of specialized agents (Architect, Dev, Data Engineer, QA, Ops):
# Launch multi-agent cooperative team
aix vibe --team fullstack "Build a high-throughput webhook receiver with Kafka forwarding"
# Run architecture tournament between 3 LLM models
aix vibe --tournament 3 "Design a distributed rate limiter with Redis Cluster backend"aix mcp (Model Context Protocol Integration)
Inspect and invoke enterprise MCP server tools:
aix mcp list # List connected MCP servers & active tools
aix mcp call <tool> <args> # Manually invoke an MCP tool with JSON arguments
aix mcp ping # Verify connectivity to remote MCP server pool3. Process Exit Codes (0-6)
Automation scripts and CI/CD pipelines rely on deterministic exit codes:
| Code | Label | Meaning | Recommended Action |
|---|---|---|---|
0 | SUCCESS | Task completed cleanly; all verification tests passed | Proceed to next pipeline stage |
1 | GENERAL_ERROR | Unhandled exception or unexpected failure | Check standard error output |
2 | VERIFICATION_FAILED | Code generated, but tests failed to pass | Inspect pytest report; increase loop iterations |
3 | CIRCUIT_BREAKER_TRIPPED | Repetitive tool failures reached breaker threshold | Check permissions or invalid diff syntax |
4 | TIMEOUT | Task runtime exceeded --timeout limit | Increase timeout or decompose prompt into smaller tasks |
5 | POLICY_VIOLATION | Action denied by Cedar governance / sandbox rule | Request elevated PAM lease or adjust policy |
6 | AUTH_EXPIRED | SSO token or API key expired | Run aix auth login to renew credentials |
4. Error Taxonomy & Troubleshooting
| Error Code | Root Cause | Remediation |
|---|---|---|
ERR_AUTH_LEASE_EXPIRED | PAM lease exceeded max TTL (8 hours) | Run aix auth login --target sn to acquire a new lease |
ERR_GATEWAY_TIMEOUT | Upstream model pool latency spike | Specify fallback model via --model claude-3-5-haiku |
ERR_SANDBOX_ESCAPE_PREVENTED | Tool attempted writing outside workspace root | Keep file paths relative to git root |
ERR_DIFF_HUNK_REJECTED | File modified concurrently on disk | Run git stash or re-synchronize working tree |