Skip to content

tools-and-cli.md

Latest commit

 

History

History
228 lines (184 loc) · 11.2 KB

tools-and-cli.md

File metadata and controls

228 lines (184 loc) · 11.2 KB
Raw

Tools and CLI

Reference for the 24 OpenCode codex-* tools and the standalone oc-codex-multi-auth bin commands.

Tools run inside OpenCode (agent/tool surface). Several diagnostics also run as a direct CLI with no agent loop and no model token cost.

OpenCode tools (24)

Registered from 24 per-file factories under lib/tools/ via createToolRegistry in lib/tools/index.ts.

Setup and guidance

Tool Purpose
codex-setup Beginner checklist / optional wizard for first-run readiness
codex-help Topic-oriented help for plugin commands and workflows
codex-next Suggested next action when stuck

Daily account use

Tool Purpose
codex-list List saved accounts, active index, tags/labels
codex-switch Switch the active account (interactive picker when index omitted)
codex-warm Open every enabled account's usage window (one minimal request each)
codex-status Active account, model family, routing / pool mode
codex-limits Live 5-hour and weekly Codex usage per account (fetched via fetchCodexUsage)
codex-reset Inspect or redeem banked rate-limit reset credit
codex-dashboard Read-only snapshot report of account eligibility, retry budgets, and refresh queue health

Account metadata and routing

Tool Purpose
codex-label Set a stable display label for an account
codex-tag Set or clear account tags for grouping/filtering
codex-note Attach a private note to an account
codex-pool Manage model account pools and preferred/strict routing modes
codex-remove Remove a saved account (confirm required)
codex-refresh Manually refresh OAuth tokens for all accounts

Diagnostics and resilience

Tool Purpose
codex-health Live health verification across accounts by refreshing each refresh token (makes network calls)
codex-metrics Runtime counters and request metrics
codex-doctor Beginner-friendly diagnostics with fix hints
codex-diag Redacted diagnostic snapshot export
codex-diff Diff account/config snapshots

Backup and secrets

Tool Purpose
codex-export Back up account storage
codex-import Restore accounts (supports dry-run)
codex-keychain Report credential backend; migrate/rollback OS keychain

Common tool examples

codex-list
codex-switch index=2
codex-warm
codex-status
codex-limits
codex-reset
codex-pool
codex-pool action="set" model="gpt-5.6-sol" accounts=[7,8]
codex-pool action="add" model="gpt-5.6-sol" accounts=[9]
codex-pool action="remove" model="gpt-5.6-sol" accounts=[7]
codex-pool action="set-mode" model="gpt-5.6-sol" poolMode="strict"
codex-pool action="clear" model="gpt-5.6-sol"
codex-label index=2 label="plus-1"
codex-tag index=2 tags="work,team-a"
codex-note index=2 note="weekend only"
codex-doctor
codex-health
codex-export
codex-import path="~/backup.json" dryRun=true
codex-keychain

Many tools accept structured output (format="json") and opt-in sensitive fields (includeSensitive=true). Prefer labels over emails; enable maskEmail in plugin config for shared screens.

Tool arguments matrix

Account indices are 1-based. Destructive tools require an explicit confirm flag.

Tool Args
codex-setup wizard? (bool), menu-driven setup when terminal supports it
codex-help topic? (setup, switch, pools, health, backup, dashboard)
codex-next format? (text | json)
codex-list tag?, format?, includeSensitive?
codex-switch index?, omit for interactive picker when supported
codex-warm format? (text | json)
codex-status format?, includeSensitive?
codex-limits format?, includeSensitive?
codex-reset action? (status | consume), creditId?, confirm? (required true to redeem), dryRun?, account? (1-based), format?, includeSensitive?
codex-dashboard format?, includeSensitive?
codex-label index?, label (empty string clears)
codex-tag index?, tags (CSV; empty clears)
codex-note index?, note (empty clears)
codex-pool action? (status | set | add | remove | clear | set-mode), model?, accounts? (1-based number array), poolMode? (preferred | strict), dryRun?, format?, includeSensitive?
codex-remove index?, confirm? (must be true to delete, omitted or false is a no-op that prints guidance)
codex-refresh (none)
codex-health format?, includeSensitive?
codex-metrics format?
codex-doctor deep?, fix? (safe automated fixes), format?
codex-diag (none), redacted snapshot only
codex-diff left, right (paths), section? (accounts | config | both)
codex-export path?, force?, timestamped? (default true when path omitted)
codex-import path, dryRun?
codex-keychain command? (status | migrate | rollback), confirm? (required for rollback when a live JSON file exists)

Operational notes

  • codex-warm / CLI warm. One lightweight request per enabled account to open usage windows. CLI exits non-zero if any account fails; disabled accounts are skipped.
  • codex-reset. Banked WHAM/rate-limit reset credits. action="consume" is irreversible and requires confirm=true (use dryRun=true to preview).
  • codex-pool. Accepts 1-based numbers but persists stable account IDs in ~/.opencode/openai-codex-auth-config.json. Restart OpenCode after mutations.
  • Tool codex-health vs CLI health. The tool refreshes every account's token against the auth server, so it makes real network calls and reports the live result. The CLI health command scans the local JSON storage and counts accounts where enabled && hasRefreshToken, with no network calls.
  • Standalone default storage. CLI commands read the global accounts file unless --config-path points at a project pool. In-session tools use the active per-project path when perProjectAccounts is true.
  • Keychain routing. status, list, health, and dashboard parse the JSON accounts file directly. warm and limits load the plugin storage runtime, so they honor CODEX_KEYCHAIN=1. doctor reads the JSON file directly unless --fix is passed, and --fix repairs through the storage runtime (an explicit --config-path forces keychain off for the repair).

Standalone CLI

Bin: oc-codex-multi-auth (also via npx -y oc-codex-multi-auth@latest …).

Commands

Command Role
install (default) Install/update OpenCode config and TUI plugin entry
doctor Local account/config diagnostics
status Account/config status
list List configured accounts
limits Live 5-hour and weekly quota usage from the usage endpoint
dashboard Prints guidance (does not start a full dashboard server)
health Local token/account health summary
diag Alias for doctor --deep
warm Open every enabled account's usage window (same idea as codex-warm) 
oc-codex-multi-auth                 # register plugin entries; preserve provider.openai
oc-codex-multi-auth install
oc-codex-multi-auth update          # cache-only; does not change config
oc-codex-multi-auth doctor
oc-codex-multi-auth status
oc-codex-multi-auth list
oc-codex-multi-auth limits
oc-codex-multi-auth dashboard
oc-codex-multi-auth health
oc-codex-multi-auth diag
oc-codex-multi-auth warm

warm exits non-zero if any account failed. Disabled accounts are skipped. limits exits 1 when it cannot load storage or any account's usage fetch fails.

A successful warm request can clear unchanged cooldown state, the responding model's own rate-limit marker, and that family's blanket marker, not other models' or other families' markers. If the account already has a subscription-quota block, warm checks live usage before clearing it; a successful response alone can be paid for with Credits and does not prove that subscription quota recovered. A failed usage check leaves the quota block in place but still clears the unchanged model and cooldown state, and the failure is reported separately. Cleanup failures are reported separately from the warm result, and newer concurrent block writes are preserved.

Installer flags

Flag Effect
(default) / --plugin-only Register plugin/TUI entries without changing provider.openai
--modern Install compact modern config (10 bases + variants)
--full Compact bases plus explicit selector entries
--legacy Explicit-only catalog (53 entries)
--dry-run Show changed config paths without values or writes
--no-cache-clear Skip clearing OpenCode plugin cache

Choose only one of --plugin-only, --modern, --full, or --legacy. Use update [--dry-run] when refreshing the package. It clears the managed OpenCode cache without reading or writing opencode.json or tui.json.

Standalone options

Flag Effect
--json Machine-readable JSON output
--include-sensitive Include sensitive identity fields in JSON where applicable
--deep Deeper diagnostics (used with doctor; implied by diag)
--fix With doctor, refresh enabled accounts and clear stale cooldown, rate-limit, and quota-exhaustion markers only after successful verification. A cleared quota stamp re-establishes itself on the next quota 429 or usage poll. Exit nonzero if any repair fails, or if the storage file cannot be read (unparseable, wrong shape, or a newer schema version).
--tag <tag> Filter accounts by tag when listing
--config-path <path> Point at a specific accounts storage path
--help / -h Print usage

Examples:

oc-codex-multi-auth status --json
oc-codex-multi-auth list --tag work
oc-codex-multi-auth warm --json
oc-codex-multi-auth doctor --deep
oc-codex-multi-auth doctor --fix --config-path ./accounts.json
npx -y oc-codex-multi-auth@latest warm

For doctor --fix, an explicit --config-path repairs only the selected JSON pool and bypasses keychain routing. Without --config-path, repair preserves enabled keychain routing, and a corrupt default storage file fails with a parse error instead of reporting an empty pool.

Related runtime concepts

  • Rotation. rotationStrategy is hybrid (default), sticky, or round-robin, set in ~/.opencode/openai-codex-auth-config.json or CODEX_AUTH_ROTATION_STRATEGY.
  • Model pools. modelAccountPools + codex-pool route effective model IDs through specific accounts. preferred mode falls back to the general pool. strict mode never leaves its configured pool.
  • Per-project accounts. Default true under ~/.opencode/projects/<project-key>/.
  • Stateless Codex contract: store: false and reasoning.encrypted_content.
  • GPT-5.6. Responses-lite path; client identity defaults to the host identity (opencode) for 5.6.

See also: