Apex CLI

Configures the AI coding assistants on your machine to use Callstack Apex (callstack/Apex).

apex init detects the assistants on your machine, lets you pick which ones to configure, shows every change it wants to make, and only then writes. Nothing changes until you say so.

Requires Node.js 22+ and npm. Nothing to install first:

npx @callstack/apex init

An npx run leaves no apex command behind, so after setup it offers to install the same version globally (npm install -g @callstack/apex), which is what makes apex undo and apex run codex work later; the rest of this README uses that short form. Say no, or run non-interactively, and every next step Apex CLI prints is spelled npx @callstack/apex … instead. Uninstalling does not undo your configs, so run apex undo first if you want them back.

Each command accepts only its own flags, and --help and the shell completions list exactly those:

apex init --wat fails fast, and so does a flag in the wrong command (apex detect --no-diff). Only --apply writes, so there is no "preview and write" to argue about. --assistants <ids> is a comma list of opencode, codex, claude, pi, cursor, copilot, ai-sdk.

Non-interactive callers (--no-interactive, --json, pipes, CI) never get a prompt and never have files changed unless they also pass --apply. --json prints a machine-readable plan with mode, applied, appliedPaths, per-file changes and nextSteps instead of the human UI. If a write fails halfway through a batch, the payload still reports what already landed plus the error, and the exit code is 1.

apex completion zsh  > "${fpath[1]}/_apex"                          # then rehash
apex completion bash >> ~/.bashrc                                   # then source ~/.bashrc
apex completion fish > ~/.config/fish/completions/apex.fish

 ┌────────────────────────────────────────────────────────────────────────────┐
 │ Apex CLI · Configure callstack/Apex for your favorite harness              │
 │                                                                            │
 │ Nothing is written until you confirm.                                      │
 └────────────────────────────────────────────────────────────────────────────┘
│
◆  Set up callstack/Apex for which assistants?  (space toggles, enter confirms)
│  OpenCode, Codex
│
◇  Set up callstack/Apex for which assistants?  (space toggles, enter confirms)
│  OpenCode, Codex


   Planned changes:

   Update     ~/.config/opencode/opencode.json
   --- ~/.config/opencode/opencode.json
   +++ ~/.config/opencode/opencode.json
   @@ -1,4 +1,19 @@
    {
      // keep this comment
   -  "theme": "dark"
   +  "theme": "dark",
   +  "provider": {
   +    "callstack.ai": { … }
   +  }
    }

   Create     ~/.codex/callstack_ai.config.toml
   --- /dev/null
   +++ ~/.codex/callstack_ai.config.toml
   @@ -0,0 +1,10 @@
   +model_provider = "callstack_ai"

   Existing files get a .apex-backup-<id> copy first.        (dimmed)
│
◇  Apply these changes?
   ✔ ~/.config/opencode/opencode.json backup: opencode.json.apex-backup-b4c42657


   Environment

   ✓ CALLSTACK_AUTH_TOKEN is set in this shell
   Apex CLI never reads, stores or logs the key itself.


   Use these commands to run callstack/Apex with your selected harnesses:

   apex run opencode  opencode --model callstack.ai/callstack/Apex        (dimmed)
   apex run codex     codex --profile callstack_ai

   ...or pick "callstack/Apex" from the UI when setting up manually.
   For more instructions, visit:
   https://app.notion.com/p/callstack/Apex-how-to-use-it-36d5d027c0f880e99d03d1c37a77382f

   If you want to undo the changes, run apex undo

Environment only shows the export CALLSTACK_AUTH_TOKEN=… line while the variable is missing; once it is set you get a green ✓ CALLSTACK_AUTH_TOKEN is set in this shell instead. The closing block shows what each apex run expands to, links the guide (the URL is never folded, so it stays clickable), and mentions apex undo only when something was actually written.

The diff is the change list: it only shows the lines that actually move, paths are shortened to ~/…, and values under keys like apiKey, token or secret are redacted, so a preview can be pasted into a ticket safely. A file Apex CLI created diffs from /dev/null, and one it is deleting diffs to /dev/null. --no-diff swaps the diff for one + key value row per setting.

apex undo re-applies the inverse of the last setup, named by the time it ran: files Apex CLI created are deleted, files it edited go back to their pre-setup bytes. It only touches a file whose current content still hashes to what Apex CLI wrote; anything you edited afterwards is left alone and reported. A setup whose remaining files can only be left alone does not block the older ones: the next apex undo moves on to the most recent setup that still has something to restore. Restores create their own backup first, so an undo is itself reversible. Apex CLI records each batch in $APEX_STATE_DIR/journal.json (default ~/.local/state/apex/journal.json, mode 0600); the last 20 batches are kept. Deleting the journal only forgets the history, it never changes a config.

OpenCode, Pi, Codex and the Copilot model JSON also declare what Apex can do, in each tool's own fields: a 262,144-token context window, 16,384 output tokens, tool calling, image input, and the none/low/medium/xhigh reasoning efforts (default medium). Cursor and Claude Code have no such fields for a custom model.

Respects XDG_CONFIG_HOME, CODEX_HOME, CLAUDE_CONFIG_DIR, PI_CODING_AGENT_DIR, XDG_STATE_HOME/APEX_STATE_DIR, and Windows APPDATA. Project-specific settings and custom OPENCODE_CONFIG files are not modified and may override global configuration. A new OpenCode config is written in the v1 format, which OpenCode 2 also reads. Older Codex releases using inline [profiles] need a manual migration or a newer Codex release.

Windows: file configuration supports Windows paths, but apex run refuses .cmd/.bat shims to avoid shell interpolation; launch the configured assistant directly or use WSL.

Provide CALLSTACK_AUTH_TOKEN through your shell or a secret manager. Apex CLI never prompts for, logs, stores or validates the key, and never writes it to a config file; configs only reference it. A hidden prompt keeps it out of your shell history:

read -r -s -p 'Callstack API key: ' CALLSTACK_AUTH_TOKEN; echo
export CALLSTACK_AUTH_TOKEN
apex run codex

Other launchers: apex run opencode, apex run claude, apex run pi, apex run codex -- --help. Launchers pass extra arguments through unchanged (without a shell), can be overridden by explicit user arguments, and never run init. apex run claude sets the gateway URL, token, attribution flag and model aliases in the child process only, leaving your default Claude provider alone.

Apex CLI will not break what you already have.

• It shows every change first, and writes nothing until you say yes. If you script it, only --apply writes.
• It copies a file next to itself before it edits that file, so you can always put the old one back.
• It keeps your comments, your other settings, and your default model.
• It never asks for your API key, writes it down, or sends it anywhere. You keep it in CALLSTACK_AUTH_TOKEN, and the CLI prints <redacted> wherever a secret would show.
• If a config file is broken, set up another way, or a link to somewhere else, Apex CLI stops and tells you. It does not overwrite it.
• apex undo gives your old setup back. It only touches files that still match what Apex CLI wrote.

How that works underneath:

• Previews print paths and key/value changes, never secrets.
• All selected configurations are parsed before any write. Malformed files, conflicting Codex profile keys and symlinked files or directories are refused, and one bad assistant blocks the whole batch instead of half-applying it.
• JSON/JSONC edits preserve comments and unrelated keys. The Callstack endpoint is set to the documented one. A key the assistant already has (in OpenCode's own key store, or in Pi's models.json, where Apex CLI 0.2 put them) is kept, so upgrading never leaves an assistant without a key; otherwise the config references CALLSTACK_AUTH_TOKEN.
• Writes use same-directory temporary files plus rename with mode 0600 (new directories 0700), and abort if the file changed on disk between planning and saving. This is not a lock or a multi-file transaction: a later I/O failure can leave earlier writes applied. apex undo cleans that up.
• Backups and newly created files are printed with every save. To recover by hand, close the assistant and restore the printed *.apex-backup-<id> file over its config after reviewing any intervening edits. Backups can contain previous secrets.
• No shell startup file is ever edited. The CLI makes no API requests and cannot verify your key or gateway access; launch a configured assistant to test the connection.

• Official Codex advanced configuration: https://developers.openai.com/codex/config-advanced/ (separate profile files for 0.134.0+; provider is placed in that profile).
• OpenCode v1 configuration: https://dev.opencode.ai/docs/config/ (JSONC and {env:VARIABLE} support).
• Pi custom models: https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/models.md ($VARIABLE key interpolation; bare uppercase names are literals in current docs).

See CONTRIBUTING.md.