CLI Tools

Aurora ships a built-in configurator for the most common AI coding CLIs. From the dashboard or the admin API, you can preview the config Aurora would write for a specific tool against your gateway, then apply it in one click. The configurator handles env vars, model lists, secret-file permissions, and tool-specific quirks.

This is a one-page version of what the dashboard Guide page shows. For the full UI walkthrough, open /admin/dashboard/guide in your browser. For the underlying API, see Admin API: CLI Tools.

What the configurator does

For each supported tool, the configurator:

1. Reads the user's current config (or notes that none exists).
2. Composes a new config that points the tool at your Aurora gateway as an OpenAI-compatible provider.
3. Sets the model list to whatever you have selected in the dashboard.
4. Adds conservative permissions so the tool does not leak your gateway key.
5. Either previews the result or writes it to the tool's standard config location.

The model picker in the dashboard only offers models that your gateway has discovered — you cannot ship a model ID that your providers do not serve.

Supported tools

can_apply=true means Aurora can write the file directly. can_apply=false means preview-only — copy the snippet by hand.

Activate

The feature is enabled by default. Toggle with:

CLI_TOOLS_ENABLED=true
CLI_TOOLS_APPLY_ENABLED=true   # set true to allow dashboard/API to write user config files

CLI_TOOLS_APPLY_ENABLED=false is the safer default for production — you do not want the gateway writing to a user's home directory without explicit operator consent.

Use the dashboard

1. Open /admin/dashboard/guide.
2. Pick a tool from the list.
3. Pick the model(s) you want to make available. The picker shows only models that are present in your gateway.
4. Either click Preview to see the snippet, or Apply (when enabled) to write the file.
5. Restart the tool if needed; some tools read config only at startup.

The configurator backs up the existing config file before overwriting. The backup path is shown in the response.

Use the API

List tools:

curl http://localhost:8080/admin/api/v1/cli-tools \
  -H "Authorization: Bearer $AURORA_MASTER_KEY"

Preview a tool's config for a specific model and base URL:

curl -X POST http://localhost:8080/admin/api/v1/cli-tools/claude-code/preview \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base_url": "http://your-aurora-host",
    "api_key": "sk-aurora-...",
    "model": "anthropic-prod/claude-sonnet-4-5"
  }'

The response includes a snippets map keyed by file path and a masked_key (your key is masked before the response is rendered).

Apply (writes to the user's home directory — requires CLI_TOOLS_APPLY_ENABLED=true):

curl -X POST http://localhost:8080/admin/api/v1/cli-tools/claude-code/apply \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base_url": "http://your-aurora-host",
    "api_key": "sk-aurora-...",
    "model": "anthropic-prod/claude-sonnet-4-5"
  }'

Reset a tool's config to its pre-Aurora state (uses the backup the configurator made):

curl -X POST http://localhost:8080/admin/api/v1/cli-tools/claude-code/reset \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"backup_path": "/home/user/.claude/settings.json.bak.2026-07-14T12-00-00Z"}'

Gotchas

• The gateway host must be reachable from where the tool runs. A localhost:8080 Aurora on a server is not useful for a tool running on your laptop. Use a public tunnel (ngrok, Cloudflare Tunnel) or a stable DNS name in that case.
• Model IDs are gateway-resolved. The picker offers <provider>/<model> IDs from your gateway. If a tool wants a different format (e.g. Cursor wants a flat string with no slash), the configurator translates.
• API_KEY vs AUTH_TOKEN. Some tools use OPENAI_API_KEY; Anthropic SDKs use ANTHROPIC_AUTH_TOKEN; the configurator picks the right one per tool.
• Permissions. Claude Code and a few others support permission rules in the same config file. The configurator appends conservative secret-file deny rules so your gateway key is not exfiltrable by an agent.
• Multiple tools can coexist. You can have Claude Code pointed at Aurora and Codex pointed at the same gateway simultaneously.
• The CLI Tools feature does not run the tool. It only writes config. You still need to start the tool yourself.

Related

• Admin API: CLI Tools — the underlying API
• Coding Agents Overview — guide-level introductions to each agent
• Claude Code — Claude Code specifics
• Codex — OpenAI Codex specifics
• OpenCode — OpenCode and other agents