Menu
Use when modifying CLI commands — chat, send, bootstrap, provider, or adding new CLI commands in src/cli/
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when modifying logging, error handling, or diagnostic messages — logger setup, transports, error diagnosis patterns in src/logger.ts and src/errors.ts
Use when modifying the trusted host process — server orchestration, message routing, IPC handler, request lifecycle, event streaming, file handling, plugin loading, or agent delegation in src/host/
Use when modifying the sandboxed agent process — runner, IPC client, local/IPC tools, tool catalog, prompt building, or identity loading in src/agent/
Use when modifying agent sandbox isolation -- Docker, Apple Container (macOS), or k8s providers in src/providers/sandbox/
Use when modifying IPC protocol between host and agent — schemas, actions, length-prefix framing, or Zod validation in ipc-schemas.ts and ipc-server.ts
AX project architecture and coding skills - use sub-skills for specific subsystems (agent, host, cli, providers, etc.)
| name | ax-cli |
| description | Use when modifying CLI commands — chat, send, bootstrap, provider, or adding new CLI commands in src/cli/ |
The CLI subsystem provides the user-facing command interface for AX. Entry point is src/cli/index.ts which routes commands via routeCommand(). Commands communicate with the AX server over a Unix socket using the OpenAI-compatible API. The chat command uses Ink (React-based terminal UI); send is a one-shot HTTP client. The provider command manages third-party npm provider packages.
Skills and MCP servers are not managed from the CLI anymore — they live in the agent's workspace (.ax/skills/<name>/SKILL.md) and go through the admin dashboard approval flow. The old ax plugin (Cowork plugins) and ax mcp commands have been removed.
| File | Responsibility |
|---|---|
src/cli/index.ts | Command router, main() entry point, runServe(), help text, --port flag, tracing init |
src/cli/send.ts | One-shot message sender, streaming + JSON output |
src/cli/bootstrap.ts | Agent identity reset (deletes SOUL.md/IDENTITY.md, copies templates) |
src/cli/provider.ts | Provider plugin management: add, remove, list, verify |
src/cli/k8s-init.ts | ax k8s init wizard — generates Helm values and K8s secrets for deployment |
src/cli/setup-server.ts | Server setup utilities (config loading, provider initialization) |
src/cli/reload.ts | Hot-reload config/skills without restart |
src/cli/utils/commands.ts | Command parsing helpers |
src/cli/utils/markdown.ts | Markdown rendering for terminal output |
| Command | Handler | Description |
|---|---|---|
ax serve (default) | runServe(args) | Start HTTP server on Unix socket (or TCP with --port); first-run triggers configure |
ax chat | runChat(args) | Interactive Ink TUI; persistent session via ConversationStore |
ax send <msg> | runSend(args) | One-shot message; ephemeral by default (no session persistence) |
ax configure | runConfigure(axHome) | First-time setup wizard (onboarding) |
ax bootstrap [agent] | runBootstrap(args) | Reset agent identity; prompts confirmation if SOUL.md exists |
ax provider <cmd> | runProvider(args) | Provider plugin management: add, remove, list, verify |
ax k8s init | runK8sInit(args) | Interactive wizard for Kubernetes deployment setup |
ax reload | runReload(args) | Hot-reload config and skills |
--port <number> -- Listen on TCP port instead of Unix socket (useful for containers or external clients)initTracing() called at startup when OTEL_EXPORTER_OTLP_ENDPOINT is setchat.ts)main:cli:default (via composeSessionId)--session <name> composes main:cli:<name>; if name contains :, passed through as-isundici.Agent({ connect: { socketPath } })App component) with streaming support~/.ax/ax.socksend.ts)session_id in request body)--session: Uses same composition rules as chat--stdin / - for piped input--no-stream (full response), --json (raw OpenAI JSON)data: lines, extracts choices[0].delta.content until [DONE]provider.ts) — npm Provider Pluginsax provider add <package> -- Install a provider plugin from npm, verify MANIFEST.json, prompt for review, write to plugins.lockax provider remove <package> -- Uninstall a provider plugin and remove from plugins.lockax provider list -- Show installed provider plugins with kind, version, and integrity statusax provider verify -- Re-verify all installed provider plugin integrity hashesFormat: colon-separated segments with minimum 3 parts.
| Pattern | Example | Use case |
|---|---|---|
<agent>:<source>:<name> | main:cli:default | Default CLI chat |
<agent>:<source>:<name> | main:cli:work | Named CLI session |
<agent>:<channel>:<scope>:<id> | main:slack:dm:U12345 | Slack DM |
| UUID (legacy) | 550e8400-... | Pre-session-ID format |
Adding a new CLI command:
CommandHandlers interface in index.tsrouteCommand() switchknownCommands Set in main()src/cli/mycommand.ts with runMyCommand(args) exportmain() command handlersshowHelp() textk8s-init.ts)Interactive wizard for generating Kubernetes deployment configuration:
small and large only (medium removed) — control resource allocation. Warm pool enabled by default..ax/skills/<name>/SKILL.md) and the admin dashboard, not through k8s-init).provider/model format (e.g., anthropic/claude-sonnet-4-20250514)extractProvider(compoundId) — Splits on first / to get provider namesecretKeyForProvider(provider) — e.g., anthropic → anthropic-api-keyenvVarForProvider(provider) — e.g., anthropic → ANTHROPIC_API_KEYkubectlexecFileSync (not execSync) to prevent shell injectionmain:cli:default becomes data/workspaces/main/cli/default/.isValidSessionId() accepts both UUID and colon format.loadDotEnv() called at CLI entry: main() calls loadDotEnv() before routing. Individual commands do not re-load.ax.yaml does not exist, runServe automatically triggers runConfigure.chat.ts imports React and Ink. The send command is plain Node.js.--port enables TCP: When --port is set, server listens on TCP in addition to (or instead of) Unix socket.OTEL_EXPORTER_OTLP_ENDPOINT is set in environment.AX_VERBOSE=1 env var for verbose mode (replaces --verbose flag in some places). Sets log level to debug via src/cli/index.ts.