Reference

# CLI Reference

GitHub Edit page

This is the curated cheatsheet. The authoritative source is always `oracle --help` (and `oracle --help --verbose` for advanced flags).

## #Commands

Command | What it does
--- | ---
`oracle [flags] -p "<prompt>"` | Run a consult.
`oracle status` | List recent sessions (see Sessions).
`oracle session <id>` | Replay or block on a stored session.
`oracle restart <id>` | Re-run with the same prompt + files.
`oracle docs check` | Check documented flags against CLI help metadata.
`oracle serve` | Run the remote browser host (see Browser Mode).
`oracle bridge claude-config` | Emit a `.mcp.json` for Claude Code (see MCP).
`oracle tui` | Interactive TUI (humans only).
`oracle-mcp` | Stdio MCP server entrypoint.

## #Core consult flags

Flag | Purpose
--- | ---
`-p, --prompt <text>` | Required prompt.
`-f, --file <paths...>` | Files / dirs / globs. Repeatable. `!` prefix = exclude.
`-e, --engine <api|browser>` | Force engine. Default: auto-pick.
`-m, --model <name>` | Single model. See Mythical Pro Agents.
`--models <list>` | Comma-separated multi-model run (API only).
`--slug <name>` | Stable session slug.
`--render` | Print the assembled bundle to stdout.
`--copy` | Copy the bundle to the clipboard.
`--write-output <path>` | Save the final answer to a file; multi-model runs add per-model files plus `<stem>.oracle.json`.
`--files-report` | Print per-file token usage.
`--dry-run [summary|json|full]` | Preview without sending.

## #Followup / lineage

Flag | Purpose
--- | ---
`--followup <id|slug|resp_…>` | Continue a saved ChatGPT browser or OpenAI/Azure Responses API session.
`--followup-model <model>` | Pick API lineage when the parent used `--models`.

## #Run control

Flag | Purpose
--- | ---
`--wait` | Block on background API runs.
`--timeout <seconds|duration|auto>` | Overall API deadline. `auto` = 60m for Pro, 120s otherwise; accepts values like `10m`.
`--background`, `--no-background` | Force Responses API background mode on/off.
`--http-timeout <ms|s|m|h>` | Override the HTTP client timeout; explicit `--timeout` values are reused when omitted.
`--allow-partial`, `--partial <mode>` | Accept partial multi-model success when mode is `ok`; default mode is `fail`.
`--preflight` | Check redacted provider readiness for requested API model(s), then exit.
`--perf-trace`, `--perf-trace-path <path>` | Write CLI startup / first-output timing trace JSON.
`--heartbeat <seconds>` | Emit progress heartbeats; browser mode reports thinking-sidecar liveness.

Notes:

- `--dry-run` is mutually exclusive with `--render` / `--render-markdown`; choose the preview or rendered bundle path.
- Missing root prompts exit nonzero after help so scripts fail closed.
- Ctrl-C exits foreground API runs with code 130. Browser runs still keep their cleanup / reattach path.
- `--perf-trace=/tmp/oracle.json` is accepted in addition to `--perf-trace-path`; `ORACLE_PERF_TRACE=1` writes a local `.oracle-perf-…json` file.

## #API endpoints

Flag | Purpose
--- | ---
`--base-url <url>` | LiteLLM / Azure / OpenRouter / proxy.
`--provider <mode>` | API route: `auto`, `openai`, or `azure`.
`--no-azure` | Ignore Azure env/config for this run.
`--route` | Print redacted API route plan, then exit.
`--azure-endpoint` | Azure OpenAI endpoint.
`--azure-deployment` | Azure deployment name.
`--azure-api-version` | Azure API version.

See OpenAI / Azure / OpenRouter and OpenRouter.

## #Browser mode

Flag | Purpose
--- | ---
`--chatgpt-url <url>` | Target a ChatGPT workspace / project folder.
`--browser-model-strategy <select|current|ignore>` | Control ChatGPT model picker.
`--browser-manual-login` | Use persistent profile + manual login (no Keychain).
`--browser-attach-running` | Attach to your already-running Chrome via DevTools.
`--browser-tab <ref>` | Reuse an existing tab (`current`, id, URL, title substring).
`--browser-thinking-time <light|standard|extended|heavy>` | Pro / Thinking model intensity.
`--browser-research deep` | Activate Deep Research mode.
`--browser-follow-up <prompt>` | Multi-turn in the same ChatGPT conversation.
`--browser-port <port>` | Pin Chrome DevTools port.
`--browser-inline-cookies[(-file)] <…>` | Supply cookies inline (no Keychain / Chrome).
`--browser-timeout`, `--browser-input-timeout`, `--browser-attachment-timeout` | Overall / input / attachment readiness timeouts (h/m/s/ms).
`--browser-recheck-delay`, `--browser-recheck-timeout` | Delayed retry after a timeout.
`--browser-auto-reattach-delay/-interval/-timeout` | Poll the existing tab when ChatGPT redirects mid-load.
`--browser-reuse-wait` | Wait for shared Chrome profile before launching.
`--browser-profile-lock-timeout` | Wait for the manual-login profile lock.
`--browser-max-concurrent-tabs` | Soft limit for shared-profile parallel runs (default 3).
`--browser-keep-browser` | Keep the browser open after the run.
`--browser-headless`, `--browser-hide-window` | Visibility controls.
`--browser-attachments <auto|never|always>` | Attach files inline vs upload.
`--browser-bundle-files`, `--browser-bundle-format <auto|text|zip>` | Bundle browser uploads as text or byte-preserving ZIP.
`--browser-chrome-path`, `--browser-cookie-path` | Override Chrome / cookie store discovery (Linux / Windows).

See Browser Mode for usage.

## #Remote browser

Flag | Purpose
--- | ---
`--remote-host <host:port>` | Use a remote `oracle serve` host.
`--remote-token <secret>` | Auth for the remote host.
`--remote-chrome <host:port>` | Attach to an existing remote Chrome session.

## #Image / media (browser)

Flag | Purpose
--- | ---
`--generate-image <file>` | Save generated image (Gemini browser; ChatGPT also saves artifacts).
`--edit-image <file>` | Edit an image (Gemini browser).
`--aspect <ratio>` | Aspect ratio for image gen.
`--youtube <url>` | Analyze a YouTube video (Gemini browser).

## #Stale session detection

Flag | Purpose
--- | ---
`--zombie-timeout <…>` | Cutoff for "stale" sessions.
`--zombie-last-activity` | Use last log entry instead of session start.

## #Environment variables

Var | Effect
--- | ---
`OPENAI_API_KEY` | Enables OpenAI API mode.
`AZURE_OPENAI_API_KEY` etc. | Enables Azure mode (paired with endpoint / deployment).
`GEMINI_API_KEY` | Enables Gemini API mode.
`ANTHROPIC_API_KEY` | Enables Claude API mode.
`OPENROUTER_API_KEY` | Enables OpenRouter ids.
`ORACLE_HOME_DIR` | Override `~/.oracle/` root.
`ORACLE_MAX_FILE_SIZE_BYTES` | Per-file size cap (default 1 MB).
`ORACLE_BROWSER_COOKIES_JSON` | Inline ChatGPT cookies (JSON / base64).
`ORACLE_BROWSER_COOKIES_FILE` | Path to cookies JSON.
`ORACLE_BROWSER_ATTACHMENT_TIMEOUT` | Attachment upload/readiness timeout for browser mode.
`ORACLE_CHATGPT_ACCOUNT_EMAIL` | Exact saved account for the Welcome back picker.

## #See also

- `oracle --help` — short usage.
- `oracle --help --verbose` — every flag, including hidden ones.
- Configuration — `~/.oracle/config.json` and project `.oracle/config.json` defaults.