CLI Providers

Octipus can run vendor CLIs (claude, gemini, codex) as subprocess agents. Octipus only spawns the binary on PATH and pipes stdin/stdout — all authentication, plan entitlements, model availability, and billing behavior are vendor-managed and change over time. Treat the notes below as pointers, not promises, and consult each vendor’s current docs.

Billing is vendor-managed

Octipus does not bill you. Each CLI handles its own auth, plan tiers, quotas, and overage billing. What counts toward a subscription vs. metered API billing is decided by the vendor and may change at any time.

Quick reference

CLI	Binary	Model flag	Headless flag	Auth
Claude Code	claude	--model <alias|id>	-p --output-format stream-json	claude auth login (OAuth) or ANTHROPIC_API_KEY
Gemini CLI	gemini	-m <name>	-p --output-format stream-json	Google OAuth, GEMINI_API_KEY, or Vertex AI
Codex CLI	codex	-m <id> (or -c model="<id>")	codex exec --json	codex login (ChatGPT OAuth) or OPENAI_API_KEY

Set the model from the Models page → CLI Tools panel in the web UI, or via the corresponding env var (CLAUDE_MODEL, GEMINI_MODEL, CODEX_MODEL). Env beats UI setting.

Claude Code

Auth. Browser OAuth via claude auth login; --console for API-key billing; ANTHROPIC_API_KEY env var. Long-lived CI tokens via claude setup-token. (cli-reference)

Plans. “Claude Pro, Max, Team, Enterprise, or Console (API)” — the free Claude.ai tier does not include Claude Code. (setup)

Model selection. --model sonnet, --model opus, or full id like --model claude-sonnet-4-6. (cli-reference)

Headless. claude -p --output-format stream-json --input-format stream-json. Octipus uses this exact pattern.

Do — pick Sonnet for cost-sensitive bulk runs and Opus for harder reasoning; the model flag overrides the local CLI default for the spawned process only.

Don’t — pass --bare. It explicitly disables OAuth and keychain reads; users authenticated via claude login will see “Not logged in”.

Gemini CLI

Auth. Three options: personal Google OAuth (browser), GEMINI_API_KEY (from AI Studio), or Vertex AI via GOOGLE_CLOUD_PROJECT + ADC. One-time browser login persists. (gemini-cli)

Plans. Personal Google OAuth gets a vendor-defined free-tier rate budget; GEMINI_API_KEY is metered usage-based; Vertex AI is enterprise-billed.

Model selection. -m gemini-2.5-flash, -m gemini-2.5-pro. (README — Quickstart)

Headless. gemini -p --output-format stream-json.

Do — let the user authenticate once with gemini auth outside Octipus; the spawned subprocess inherits the credential cache.

Don’t — combine -y / --yolo from inside Octipus. It auto-approves all tools and bypasses Octipus’s permission gates.

Codex CLI

Auth. codex login (ChatGPT browser OAuth) or OPENAI_API_KEY. Vendor warns that Codex caches login details locally in plaintext — treat like a password. (auth)

Plans. “ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex.” API-key auth is usage-based at standard API rates. Fast mode is ChatGPT-account only. (codex/cli)

Model selection. -m gpt-5.5, -m o3, etc. Octipus uses the equivalent -c model="<id>" form so the override survives any local ~/.codex/config.toml default. (features)

Headless. codex exec --json is the documented non-interactive subcommand. Octipus uses this.

Do — set CODEX_MODEL per shell when delegating to a cheaper variant; consider codex mcp-server if you want tighter integration than subprocess wrapping.

Don’t — use -s danger-full-access. It removes Codex’s own sandboxing, which Octipus’s permission engine relies on as a second line of defense.

How Octipus passes the model flag

When you set a model on a CLI tool entry in Models → CLI Tools, Octipus stores it in the model’s metadata.cliAgent.model field. At spawn time the adapters in src/core/cli-adapters.ts translate that value to:

• Claude: appends --model <value> to the argv
• Gemini: appends -m <value> to the argv
• Codex: appends -c model="<value>" to the argv (overrides ~/.codex/config.toml)

Env vars (CLAUDE_MODEL, GEMINI_MODEL, CODEX_MODEL) take precedence over the stored setting. If none is set, the CLI uses its own default — which the vendor controls and may rotate at any time.

Anti-patterns Octipus refuses

CLI	Refused flag	Why
Claude	--bare	breaks OAuth/keychain, users get “Not logged in”
Gemini	-y / --yolo	bypasses Octipus’s permission gates
Codex	-s danger-full-access	undermines sandbox the permission engine relies on

If you need any of these flags for a one-off run, invoke the CLI directly outside Octipus.

Vendor docs (always check current)

• Claude Code — https://code.claude.com/docs/en/cli-reference
• Gemini CLI — https://github.com/google-gemini/gemini-cli
• Codex CLI — https://developers.openai.com/codex/cli