nils-codex-cli 0.3.5

CLI crate for nils-codex-cli in the nils-cli workspace.
Documentation

codex-cli

Overview

codex-cli is a provider-specific Rust CLI for OpenAI/Codex workflows: Codex execution wrappers, auth/secret management, Codex diagnostics, config output, and Starship rendering.

Usage

Usage:
  codex-cli <group> <command> [args]
  codex-cli starship [options]

Groups:
  agent    prompt | advice | knowledge | commit
  auth     login | use | save | refresh | auto-refresh | current | sync
  diag     rate-limits
  config   show | set
  starship (options)

Help:
  codex-cli help
  codex-cli <group> help

Scope boundary

Job Primary owner
OpenAI/Codex auth, Codex prompt wrappers, Codex rate-limit diagnostics, Starship codex-cli
Multi-provider registry/selection (provider), provider-neutral doctor/debug/workflow agentctl
Local automation tool orchestration (macos-agent, screen-record, image-processing, fzf-cli) agentctl
  • codex-cli owns only provider-specific OpenAI/Codex operations (agent, auth, diag rate-limits, config, starship).
  • Provider-neutral orchestration (provider, diag, debug, workflow, automation) belongs to agentctl.
  • Compatibility behavior: existing codex-cli commands stay stable for provider-specific workflows.
  • Compatibility shim: wrappers/codex-cli forwards provider|debug|workflow|automation to agentctl when available.
  • Canonical hint text (wrapper/help/docs): use agentctl <command> for provider-neutral orchestration.
  • Provider adapter implementation guidance: ../agent-runtime-core/README.md and ../../docs/runbooks/provider-onboarding.md.

Commands

agent

  • prompt [PROMPT...]: Run a raw prompt through codex exec.
  • advice [QUESTION...]: Request actionable engineering advice.
  • knowledge [CONCEPT...]: Request a concept explanation.
  • commit [-p|--push] [-a|--auto-stage] [EXTRA...]: Run the semantic-commit workflow.

auth

  • login [--api-key|--device-code]: Login via ChatGPT browser flow (chatgpt-browser, default), ChatGPT device-code flow (chatgpt-device-code), or API key flow (api-key). --api-key and --device-code are mutually exclusive (64 on invalid usage).
  • use <name|email>: Switch to a secret by name or email.
  • save [--yes] <secret.json>: Save active CODEX_AUTH_FILE into CODEX_SECRET_DIR with an explicit file name. If target exists, interactive mode prompts for overwrite; non-interactive and JSON mode require --yes to overwrite.
  • refresh [secret.json]: Refresh OAuth tokens.
  • auto-refresh: Refresh stale tokens across auth + secrets.
  • current: Show which secret matches CODEX_AUTH_FILE.
  • sync: Sync CODEX_AUTH_FILE back into matching secrets.

Auth examples:

  • codex-cli auth login: ChatGPT browser login.
  • codex-cli auth login --device-code: ChatGPT device-code login.
  • codex-cli auth login --api-key: OpenAI API key login.
  • codex-cli auth save team-alpha.json: Save and prompt before overwrite when applicable.
  • codex-cli auth save --yes team-alpha.json: Force overwrite without prompt.

diag

  • rate-limits [options] [secret.json]: Rate-limit diagnostics. Options: -c, -d/--debug, --cached, --no-refresh-auth, --json, --one-line, --all, --async, --jobs <n>.

config

  • show: Print effective configuration values.
  • set <key> <value>: Emit a shell snippet for the current shell.

starship

  • starship [--no-5h] [--ttl <duration>] [--time-format <strftime>] [--show-timezone] [--refresh] [--is-enabled]: Render or refresh the Starship line. Default reset time uses local time without timezone; --show-timezone adds the local offset.

JSON contract (service consumers)

  • Human-readable text is the default output mode.
  • Machine-readable JSON mode is explicit: use --format json (preferred) or --json where supported for compatibility.
  • Contract spec: docs/specs/codex-cli-diag-auth-json-contract-v1.md
  • Consumer runbook: ../../docs/runbooks/codex-cli-json-consumers.md
  • Covered surfaces: diag rate-limits (single/all/async) and auth login|use|save|refresh|auto-refresh|current|sync.

Environment

  • CODEX_ALLOW_DANGEROUS_ENABLED=true is required for agent commands.
  • CODEX_CLI_MODEL and CODEX_CLI_REASONING set codex exec defaults.
  • CODEX_SECRET_DIR controls the secret directory path. When unset, it defaults to ~/.config/codex_secrets.
  • CODEX_AUTH_FILE controls the active auth file path. When unset, it defaults to ~/.codex/auth.json.
  • CODEX_SECRET_CACHE_DIR controls secret cache timestamps.
  • CODEX_STARSHIP_ENABLED=true enables Starship output.
  • CODEX_STARSHIP_TTL overrides the cache TTL.

Dependencies

  • codex is required for agent commands.
  • git is required for agent commit.
  • semantic-commit and git-scope are optional for agent commit (fallbacks apply).

Exit codes

  • 0: success and help output.
  • 64: usage or argument errors.
  • 1: operational errors.