cli-reference.md

title	CLI Reference
description	Every flag you'll actually use, grouped by what it does. Run `oracle --help --verbose` for the full hidden list.

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	Keep the original CLI attached until the session completes.
--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 and stops an attached local Pro browser worker. Unexpected foreground termination leaves the detached browser worker running so the session can still finish.
• --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-cookie-sync	Explicitly copy cookies from live Chrome; prefer manual login because token rotation can invalidate the live session.
--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|extra-high|pro|heavy>	Effort intensity; pro selects the Pro tier and fails closed if unconfirmed, other unmatched tiers keep the current effort.
--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.