### Install from Homebrew Tap

Source: https://github.com/steipete/oracle/blob/main/docs/RELEASING.md

Install the package using Homebrew after it has been tapped. This sequence ensures the package is correctly installed and its version can be verified.

```bash
brew uninstall oracle || true
```

```bash
brew tap steipete/tap || true
```

```bash
brew install steipete/tap/oracle
```

```bash
oracle --version
```

```bash
brew uninstall oracle
```

--------------------------------

### Start LiteLLM Server

Source: https://github.com/steipete/oracle/blob/main/docs/openai-endpoints.md

Starts the LiteLLM server with a specified model. This is a prerequisite for connecting Oracle to LiteLLM.

```bash
litellm --model azure/gpt-4-turbo
```

--------------------------------

### Start Oracle Remote Service on VM

Source: https://github.com/steipete/oracle/blob/main/docs/debug/remote-chrome.md

Commands to start the Oracle remote service on a VM. Ensure bun is installed and added to the PATH. This command starts the service listening on a specified port with a given token.

```bash
cd ~/Projects/oracle
export PATH="$HOME/.bun/bin:$PATH"
./runner pnpm run oracle -- serve --port 49810 --token cd93955b64d5afcb946a4a4a89651313
```

--------------------------------

### Provider Readiness Output Example

Source: https://github.com/steipete/oracle/blob/main/docs/refactor/ux.md

Example output from `oracle doctor --providers` showing the status of configured providers, keys, and routing.

```text
Provider readiness

OpenAI: ok
  key: OPENAI_API_KEY=sk-...a91
  base: api.openai.com
  route gpt-5.4: OpenAI Responses API

Azure OpenAI: configured, inactive
  endpoint: my-resource.openai.azure.com
  key: AZURE_OPENAI_API_KEY=az-...32c
  route gpt-5.4: ignored because --provider openai

Anthropic: auth failed
  key: ANTHROPIC_API_KEY=sk-...9bc
  error: invalid x-api-key

Gemini: auth failed
  key: GEMINI_API_KEY=AIza...77e
  error: API key expired
```

--------------------------------

### Provider Route Plan Output Example

Source: https://github.com/steipete/oracle/blob/main/docs/refactor/ux.md

Example output showing the planned route for each model, including provider, base URL, and key status.

```text
Route plan

gpt-5.4
  provider: OpenAI
  base: api.openai.com
  key: OPENAI_API_KEY=sk-...a91
  azure: ignored, AZURE_OPENAI_ENDPOINT is set

gemini-3-pro
  provider: Google Gemini
  base: generativelanguage.googleapis.com
  key: GEMINI_API_KEY=AIza...77e
```

--------------------------------

### Example User Configuration (~/.oracle/config.json)

Source: https://github.com/steipete/oracle/blob/main/docs/configuration.md

This snippet shows a comprehensive example of a user's local Oracle configuration file. It includes settings for the default engine, model, search preferences, browser integration options, Azure OpenAI defaults, and API-specific overrides. Use this as a template for your own `~/.oracle/config.json`.

```json5
{
  // Default engine when neither CLI flag nor env decide
  engine: "api", // or "browser"
  model: "gpt-5.5-pro", // older gpt-5.x-pro aliases → gpt-5.5-pro
  search: "on", // "on" | "off"

  notify: {
    enabled: true, // default notifications (still auto-mutes in CI/SSH unless forced on)
    sound: false, // play a sound on completion
    muteIn: ["CI", "SSH"], // auto-disable when these env vars are set
  },

  browser: {
    chromeProfile: "Default",
    chromePath: null,
    chromeCookiePath: null,
    chatgptUrl: "https://chatgpt.com/", // root is fine; folder URLs also work
    url: null, // alias for chatgptUrl (kept for back-compat)
    // Remote browser bridge (preferred place to store remote host settings)
    remoteHost: "127.0.0.1:9473",
    remoteToken: "…", // written by `oracle bridge client` (kept private; not printed by default)
    remoteViaSshReverseTunnel: { ssh: "user@linux-host", remotePort: 9473 }, // optional metadata
    debugPort: null, // fixed DevTools port (env: ORACLE_BROWSER_PORT / ORACLE_BROWSER_DEBUG_PORT)
    timeoutMs: 1200000,
    inputTimeoutMs: 30000,
    attachmentTimeoutMs: 90000, // wait for file upload/readiness before clicking Send (default: 45s)
    cookieSyncWaitMs: 0, // wait (ms) before retrying cookie sync when Chrome cookies are empty/locked
    assistantRecheckDelayMs: 0, // wait this long after timeout, then retry capture (0 = disabled)
    assistantRecheckTimeoutMs: 120000, // time budget for the recheck attempt (default: 2m)
    reuseChromeWaitMs: 10000, // wait for a shared Chrome profile to appear before launching (parallel runs)
    profileLockTimeoutMs: 300000, // wait for the manual-login profile lock before sending (parallel runs)
    maxConcurrentTabs: 3, // soft limit for concurrent ChatGPT tabs using one manual-login profile
    autoReattachDelayMs: 0, // delay before starting periodic auto-reattach attempts (0 = disabled)
    autoReattachIntervalMs: 0, // interval between auto-reattach attempts (0 = disabled)
    autoReattachTimeoutMs: 120000, // time budget per auto-reattach attempt (default: 2m)
    modelStrategy: "select", // select | current | ignore (ChatGPT only; ignored for Gemini web)
    thinkingTime: "extended", // light | standard | extended | heavy (ChatGPT Thinking/Pro models)
    researchMode: "off", // off | deep (ChatGPT Deep Research; browser only)
    manualLogin: false, // set true to reuse a persistent automation profile and sign in once (Windows defaults to true when unset)
    manualLoginProfileDir: null, // override profile dir (or set ORACLE_BROWSER_PROFILE_DIR)
    headless: false,
    hideWindow: false,
    keepBrowser: false,
    manualLoginCookieSync: false, // allow cookie sync even in manual-login mode
  },

  // Azure OpenAI defaults (only used when endpoint is set)
  azure: {
    endpoint: "https://your-resource-name.openai.azure.com/",
    deployment: "gpt-5-1-pro",
    apiVersion: "2025-04-01-preview", // optional legacy knob; Azure v1 Responses runs do not require it
  },

  heartbeatSeconds: 30, // default heartbeat interval
  maxFileSizeBytes: 2097152, // raise/lower the per-file attachment guard (bytes)
  filesReport: false, // default per-file token report
  background: true, // default background mode for API runs
  sessionRetentionHours: 72, // prune cached sessions older than 72h before each run (0 disables)
  promptSuffix: "// signed-off by me", // appended to every prompt
  apiBaseUrl: "https://api.openai.com/v1", // override for LiteLLM / custom gateways
  // API-only, user-config-only overrides for known model keys.
  modelOverrides: {
    "gpt-5.5": {
      apiModel: "gateway-model", // on-wire id exposed by the gateway
      reasoning: { effort: "xhigh" }, // or null to clear the bundled effort
      inputLimit: 1050000,
      pricing: { inputPerToken: 0.000005, outputPerToken: 0.00003 },
    },
  },
}
```

--------------------------------

### Timeout Plan Output Example

Source: https://github.com/steipete/oracle/blob/main/docs/refactor/ux.md

Example output showing the resolved timeout values for overall, transport, and session cutoff.

```text
Timeouts
  overall: 10m
  transport: 10m
  session stale cutoff: 10m
```

--------------------------------

### MCPorter Example (stdio)

Source: https://github.com/steipete/oracle/blob/main/docs/mcp.md

Example configuration for mcporter using stdio to run the oracle-mcp command.

```json
{
  "name": "oracle",
  "type": "stdio",
  "command": "npx",
  "args": ["@steipete/oracle", "oracle-mcp"]
}
```

--------------------------------

### Get Oracle CLI Help Verbose

Source: https://github.com/steipete/oracle/blob/main/skills/oracle/SKILL.md

Access detailed help information for advanced configuration options.

```bash
npx -y @steipete/oracle --help --verbose
```

--------------------------------

### Start Oracle Bridge Host Service (Windows)

Source: https://github.com/steipete/oracle/blob/main/docs/bridge.md

Run this on the Windows machine signed into ChatGPT to start the bridge host service. It binds a local instance, generates a token, and sets up an SSH reverse tunnel to the Linux host. Connection details are saved to `~/.oracle/bridge-connection.json`.

```powershell
oracle bridge host --token auto --ssh user@your-linux-host
```

--------------------------------

### Unified Timeout Semantics Examples

Source: https://github.com/steipete/oracle/blob/main/docs/refactor/ux.md

Examples demonstrating how to set overall and HTTP timeouts. `--timeout auto` enables automatic detection.

```sh
oracle --timeout 10m ...
oracle --timeout 10m --http-timeout 30s ...
oracle --timeout auto ...
```

--------------------------------

### Partial Success Output Example

Source: https://github.com/steipete/oracle/blob/main/docs/refactor/ux.md

Example output when partial success is enabled, showing succeeded and failed models, saved outputs, and session information.

```text
Multi-model result: partial success, 1/3 succeeded

Saved outputs:
- gpt-5.4 -> /tmp/name.gpt-5.4.md

Failures:
- claude-4.6-sonnet: auth failed, invalid x-api-key
- gemini-3-pro: auth failed, API key expired

Session:
- oracle session 20260515-naming-panel
```

--------------------------------

### Docs/Help Drift Example

Source: https://github.com/steipete/oracle/blob/main/docs/refactor/ux.md

An example of a documentation drift failure, where a flag mentioned in skill documentation is not present in the packed CLI help.

```text
Docs/help drift:
- skills/oracle/SKILL.md mentions --no-azure
- packed CLI help does not expose --no-azure
```

--------------------------------

### Launch Chrome with User Profile

Source: https://github.com/steipete/oracle/blob/main/docs/manual-tests.md

Starts a Chrome instance using your existing profile, preserving login sessions and cookies.

```bash
pnpm tsx scripts/browser-tools.ts start --profile
```

--------------------------------

### Install Oracle via npm or pnpm

Source: https://github.com/steipete/oracle/blob/main/docs/install.md

Install Oracle globally using npm or pnpm. Requires Node.js version 24 or newer. After installation, you can run `oracle --help` or `oracle --version`.

```bash
npm install -g @steipete/oracle
```

```bash
pnpm add -g @steipete/oracle
```

```bash
oracle --help
```

```bash
oracle --version
```

--------------------------------

### Start Oracle Remote Service

Source: https://github.com/steipete/oracle/blob/main/docs/browser-mode.md

Starts the Oracle service on the host machine. It picks a free port, launches Chrome, and provides an access token. Use flags like `--host`, `--port`, or `--token` to customize. Ensure the host Chrome profile is signed into ChatGPT.

```bash
oracle serve
```

--------------------------------

### Install Oracle via Homebrew

Source: https://github.com/steipete/oracle/blob/main/docs/install.md

Use this command to install Oracle on macOS or Linux using Homebrew. The tap also publishes the `oracle-notifier` macOS helper.

```bash
brew install steipete/tap/oracle
```

--------------------------------

### Project-Scoped Claude (.mcp.json) Example

Source: https://github.com/steipete/oracle/blob/main/docs/mcp.md

Example configuration for project-scoped Claude, specifying the oracle-mcp server.

```json
{
  "mcpServers": {
    "oracle": { "type": "stdio", "command": "npx", "args": ["@steipete/oracle", "oracle-mcp"] }
  }
}
```

--------------------------------

### Oracle Remote Service Logs

Source: https://github.com/steipete/oracle/blob/main/docs/debug/remote-chrome.md

Example logs indicating a successfully started Oracle remote service. These logs confirm the listening address and the access token being used.

```text
Listening at 0.0.0.0:49810
Access token: cd93955b64d5afcb946a4a4a89651313
```

--------------------------------

### Codex Skill Installation

Source: https://github.com/steipete/oracle/blob/main/docs/agents.md

Copy the bundled Oracle skill into `~/.codex/skills/` for use with Codex. Codex will automatically pick it up.

```bash
mkdir -p ~/.codex/skills
cp -R skills/oracle ~/.codex/skills/oracle
```

--------------------------------

### Run Oracle CLI Commands

Source: https://github.com/steipete/oracle/blob/main/docs/index.md

Examples of using the Oracle CLI for different tasks. The browser path drives ChatGPT directly, while the API path allows multi-model cross-checking. The render option assembles the bundle for copying, and status commands manage sessions.

```bash
# Browser path — no API key, drives ChatGPT directly (default: GPT-5.5 Pro).
oracle --engine browser -p "Review the storage layer for schema drift" --file "src/**/*.ts"
```

```bash
# API path — multi-model cross-check in one run.
oracle -p "Cross-check the data layer assumptions" \
  --models gpt-5.5-pro,gemini-3-pro,claude-4.6-sonnet \
  --file "src/**/*.ts"
```

```bash
# Manual fallback — assemble the bundle and copy it to your clipboard.
oracle --render --copy -p "Architecture review" --file "src/**/*.ts"
```

```bash
# Sessions you can replay or continue.
oracle status --hours 72
oracle session <id> --render
oracle --followup <id> -p "Re-evaluate with this new context" --file "src/**/*.ts"
```

--------------------------------

### Run Oracle MCP Stdio Server

Source: https://github.com/steipete/oracle/blob/main/README.md

Start the standard input/output server for the Oracle MCP. This command is used to initiate the MCP service.

```bash
npx -y @steipete/oracle oracle-mcp
```

--------------------------------

### Run Oracle without installing

Source: https://github.com/steipete/oracle/blob/main/docs/install.md

Execute Oracle using npx or pnpx for CI, ad-hoc scripts, or environments where a global installation is not desired. Consider pinning the version in CI to avoid re-downloading.

```bash
npx -y @steipete/oracle --help
```

```bash
pnpx @steipete/oracle --help
```

--------------------------------

### Test Package Installation via npx

Source: https://github.com/steipete/oracle/blob/main/docs/RELEASING.md

Execute the Oracle package using npx from a clean directory to ensure it installs and runs correctly without local dependencies. The --dry-run flag simulates the execution without making changes.

```bash
npx @steipete/oracle@X.Y.Z "Smoke from empty dir" --dry-run
```

--------------------------------

### Local Manual Login Browser Session (Linux Desktop)

Source: https://github.com/steipete/oracle/blob/main/docs/bridge.md

Starts a local browser session on a Linux desktop for Oracle, reusing a local signed-in Chrome profile without a Windows bridge. Use this when physically on the Linux machine and wanting to leverage existing browser logins.

```bash
ORACLE_HOME_DIR=~/.oracle-local \
ORACLE_BROWSER_PROFILE_DIR=~/.oracle-local/browser-profile \
oracle --engine browser --browser-manual-login --browser-keep-browser -p "hello"
```

--------------------------------

### Oracle CLI Usage: Multi-Model Comparison (GPT + Claude)

Source: https://github.com/steipete/oracle/blob/main/docs/anthropic.md

Example of using the Oracle CLI to compare responses from GPT and Claude models for mitigation step proposals.

```bash
oracle --models gpt-5.1-pro,claude-4.6-sonnet --prompt "Propose mitigation steps" --file docs/plan.md
```

--------------------------------

### Host Remote Browser Automation

Source: https://github.com/steipete/oracle/blob/main/skills/oracle/SKILL.md

Start a remote browser host service that can be controlled by an Oracle CLI client.

```bash
oracle serve --host 0.0.0.0 --port 9473 --token <secret>
```

--------------------------------

### Multi-turn Browser Consults with Follow-ups

Source: https://github.com/steipete/oracle/blob/main/docs/browser-mode.md

Use multi-turn consults for in-depth reviews where a single prompt might lead to shallow answers. This example demonstrates chaining follow-up prompts to challenge previous responses and refine the final decision.

```bash
oracle --engine browser \
  --model gpt-5.5-pro \
  --browser-thinking-time heavy \
  -p "Review this migration plan and identify the top risks." \
  --file docs/migration-plan.md \
  --browser-follow-up "Challenge your previous recommendation. What would fail in production?" \
  --browser-follow-up "Now give the final decision with the smallest safe next step."
```

--------------------------------

### Start Claude in Tmux

Source: https://github.com/steipete/oracle/blob/main/docs/testing/mcp-smoke.md

Initiate a tmux session to run Claude with MCP integration. Ensure OPENAI_API_KEY is exported and the Oracle MCP is registered with Claude.

```bash
tmux new -s claude-smoke 'cd /Users/steipete/Projects/oracle && OPENAI_API_KEY=$OPENAI_API_KEY claude --permission-mode bypassPermissions --mcp-config ~/.mcp/oracle.json'
```

--------------------------------

### Install Oracle Codex Skill

Source: https://github.com/steipete/oracle/blob/main/README.md

Copy the bundled skill from the repository to your Codex skills folder. This allows Codex to use Oracle's capabilities.

```bash
mkdir -p ~/.codex/skills
cp -R skills/oracle ~/.codex/skills/oracle
```

--------------------------------

### Get Help for chrome-devtools-mcp

Source: https://github.com/steipete/oracle/blob/main/docs/manual-tests.md

Displays the help information for the chrome-devtools-mcp command, listing available switches for customization such as custom Chrome binary, headless mode, and viewport settings.

```bash
npx chrome-devtools-mcp@latest --help
```

--------------------------------

### Claude Code Skill Installation

Source: https://github.com/steipete/oracle/blob/main/docs/agents.md

Copy the bundled Oracle skill into `~/.claude/skills/` for use with Claude Code. Claude Code will load `SKILL.md` when trigger conditions match.

```bash
mkdir -p ~/.claude/skills
cp -R skills/oracle ~/.claude/skills/oracle
```

--------------------------------

### Start Chrome with Remote Debugging Enabled

Source: https://github.com/steipete/oracle/blob/main/docs/browser-mode.md

Launch Chrome with remote debugging enabled on the machine that will host the browser window. Ensure the address is set to 0.0.0.0 if connecting from another machine and secure the connection if the network is untrusted.

```bash
google-chrome \
  --remote-debugging-port=9222 \
  --remote-debugging-address=0.0.0.0 \
  --user-data-dir=/path/to/profile \
  --profile-directory='Default'
```

--------------------------------

### Drive Claude with Agent Send Script

Source: https://github.com/steipete/oracle/blob/main/docs/testing/mcp-smoke.md

Use a helper script to interact with the Claude session started in tmux. This example calls the oracle sessions MCP tool.

```bash
bun scripts/agent-send.ts --session claude-smoke --wait-ms 800 --entry double -- \
  'Call the oracle sessions MCP tool with {"limit":1,"detail":true} and show the result'
```

--------------------------------

### Initial and Follow-up API Runs

Source: https://github.com/steipete/oracle/blob/main/docs/followup.md

Demonstrates an initial API run to audit an authentication flow, followed by a subsequent run using `--followup` to re-evaluate with new files. This pattern is useful for iterative development and cost savings.

```bash
# Initial run
oracle --model gpt-5.5-pro --slug arch-review \
  -p "Audit the auth flow end-to-end" \
  --file "src/auth/**"

# Later — continue with new files
oracle --followup arch-review \
  -p "Re-evaluate now that the rate-limiter is wired in." \
  --file "src/auth/rate-limiter.ts"
```

--------------------------------

### Set Up and Run Live OpenAI API Tests

Source: https://github.com/steipete/oracle/blob/main/docs/manual-tests.md

Export your OpenAI API key and set the ORACLE_LIVE_TEST environment variable to 1 to enable live tests. Then, run the specified Vitest file.

```bash
export OPENAI_API_KEY=sk-...
export ORACLE_LIVE_TEST=1
pnpm vitest run tests/live/openai-live.test.ts
```

--------------------------------

### Startup and Performance Trace

Source: https://github.com/steipete/oracle/blob/main/skills/oracle/SKILL.md

Enables performance tracing for the CLI startup and execution, saving the trace data to a specified JSON file. Useful for diagnosing slow performance.

```bash
npx -y @steipete/oracle --perf-trace --perf-trace-path /tmp/oracle-perf.json --dry-run summary -p "<task>" --file "src/**"
```

--------------------------------

### Explicit HTTP Timeout Example

Source: https://github.com/steipete/oracle/blob/main/docs/refactor/ux.md

Example output when an explicit, shorter HTTP timeout is set, with a note about potential early transport failure.

```text
Timeouts
  overall: 10m
  transport: 30s
  note: transport can fail before overall timeout
```

--------------------------------

### Show Help for Browser CLI

Source: https://github.com/steipete/oracle/blob/main/docs/manual-tests.md

Displays available commands and usage instructions for the browser CLI tool.

```bash
pnpm tsx scripts/browser-tools.ts --help
```

--------------------------------

### Update Oracle via Homebrew or npm

Source: https://github.com/steipete/oracle/blob/main/docs/install.md

Update your Oracle installation using either Homebrew or npm. Use `oracle --version` to check the currently installed build.

```bash
brew upgrade oracle
```

```bash
npm update -g @steipete/oracle
```

--------------------------------

### Oracle AGENTS.md/CLAUDE.md Configuration

Source: https://github.com/steipete/oracle/blob/main/docs/agents.md

Add this to your project's AGENTS.md or CLAUDE.md to enable Oracle. Run `npx -y @steipete/oracle --help` once per session before first use.

```markdown
- Oracle bundles a prompt plus the right files so a Pro model (GPT-5.5 Pro,
  Gemini 3 Pro, Claude Opus) can answer with real repo context. Use when stuck,
  debugging hard bugs, doing architecture review, or cross-validating a plan.
- Run `npx -y @steipete/oracle --help` once per session before first use.
```

--------------------------------

### Include Files and Directories with Oracle CLI

Source: https://github.com/steipete/oracle/blob/main/skills/oracle/SKILL.md

Demonstrates how to use the --file argument to include specific files, directories, or globs. Multiple entries can be provided.

```bash
--file "src/**"
```

```bash
--file src/index.ts
```

```bash
--file docs --file README.md
```

--------------------------------

### Performance Trace

Source: https://github.com/steipete/oracle/blob/main/README.md

Traces startup and time-to-first-output for a dry run summary, saving performance data to a specified JSON file. Useful for optimizing tool performance.

```bash
npx -y @steipete/oracle --perf-trace --perf-trace-path /tmp/oracle-perf.json \
  --dry-run summary -p "Quick smoke"
```

--------------------------------

### Performance Tracing with Oracle CLI

Source: https://github.com/steipete/oracle/blob/main/skills/oracle/SKILL.md

Enable performance tracing for startup and first-output timing using --perf-trace or the ORACLE_PERF_TRACE environment variable.

```bash
--perf-trace
```

```bash
ORACLE_PERF_TRACE=1
```

--------------------------------

### Run Live API Smoke Tests (Pro)

Source: https://github.com/steipete/oracle/blob/main/docs/testing.md

Execute live API smoke tests including OpenAI pro. Requires setting ORACLE_LIVE_TEST and OPENAI_API_KEY environment variables. Expect real usage and costs.

```bash
ORACLE_LIVE_TEST=1 OPENAI_API_KEY=… pnpm test:pro
```

--------------------------------

### Run GPT-5.5 Simple Prompt (Longer Response)

Source: https://github.com/steipete/oracle/blob/main/docs/manual-tests.md

Execute a simple prompt with the GPT-5.5 model, expecting a response that may take 2-3 minutes. Confirm the answer arrives and is unique.

```bash
pnpm run oracle -- --engine browser --model gpt-5.5 --prompt "List two reasons Markdown is handy"
```

--------------------------------

### Kick off API Multi-Run

Source: https://github.com/steipete/oracle/blob/main/docs/manual-tests.md

Initiates an API multi-run with specified models and a prompt. Expects sequential output sections per model without interleaved tokens.

```bash
pnpm run oracle -- --models "gpt-5.1-pro,gemini-3-pro" --prompt "Compare the moon & sun."
```

--------------------------------

### Run Mcporter Browser Consult

Source: https://github.com/steipete/oracle/blob/main/docs/testing/mcp-smoke.md

Execute a browser-based consult using mcporter. This utilizes a built-in browserConfig and requires Chrome to be installed.

```bash
mcporter call oracle-local.consult \
  prompt:"Browser smoke" \
  model:"GPT-5.2" \
  engine:"browser" \
  --config config/mcporter.json
```

--------------------------------

### Run CLI Browser Smoke Test

Source: https://github.com/steipete/oracle/blob/main/docs/testing/mcp-smoke.md

Execute a smoke test for the CLI using the browser engine. Requires Chrome installed on macOS.

```bash
pnpm run oracle -- --engine browser --model "GPT-5.2" --prompt "Browser smoke: say two words"
```

--------------------------------

### Test Missing Prompt Error

Source: https://github.com/steipete/oracle/blob/main/docs/manual-tests.md

Tests CLI startup with an API engine but no prompt. Expects help output and a nonzero exit code.

```bash
pnpm run oracle -- --engine api
```

--------------------------------

### Reproduce Oracle Context with File

Source: https://github.com/steipete/oracle/blob/main/skills/oracle/SKILL.md

To reproduce the exact context of a previous Oracle run, use the `--file` option with the same prompt. Oracle runs are one-shot and do not retain memory between executions.

```bash
oracle --file ...
```

--------------------------------

### Oracle CLI Usage: Single Model (Sonnet)

Source: https://github.com/steipete/oracle/blob/main/docs/anthropic.md

Example of using the Oracle CLI to interact with the Claude 4.6 Sonnet model for summarization.

```bash
oracle --engine api --model claude-4.6-sonnet --prompt "Summarize the design doc" --file docs/design.md
```

--------------------------------

### Check Provider Readiness

Source: https://github.com/steipete/oracle/blob/main/docs/openai-endpoints.md

Use these commands to check if providers and models are ready before running an API. They exit before sending a prompt or creating a session.

```bash
oracle doctor --providers --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro
oracle --preflight --models gpt-5.4,gemini-3-pro
oracle --route --model gpt-5.4
```

--------------------------------

### Render and Copy Bundle

Source: https://github.com/steipete/oracle/blob/main/docs/quickstart.md

This command renders a bundle for an architecture review and copies it to your clipboard, suitable for pasting into other AI models.

```bash
oracle --render --copy -p "Architecture review" --file "src/**/*.ts"
```

--------------------------------

### Promote npm Package Version

Source: https://github.com/steipete/oracle/blob/main/docs/RELEASING.md

Assign a distribution tag (e.g., 'latest') to a specific version of the @steipete/oracle package. This makes it the default version installed by npm.

```bash
npm dist-tag add @steipete/oracle@X.Y.Z latest
```

--------------------------------

### Run Local Oracle CLI Script

Source: https://github.com/steipete/oracle/blob/main/skills/oracle/SKILL.md

Execute the Oracle CLI using a local Node.js script. This is an alternative to running the installed CLI, useful for testing changes.

```bash
node ~/Projects/oracle/dist/scripts/run-cli.js ...
```

--------------------------------

### Choosing Bundle Format

Source: https://github.com/steipete/oracle/blob/main/docs/browser-mode.md

Select the format for bundled files with `--browser-bundle-format`. `auto` uses text for text-only inputs and ZIP for mixed inputs. `text` creates a single Markdown-style bundle, while `zip` archives original file bytes.

```bash
--browser-bundle-format <auto|text|zip>
```

--------------------------------

### Build Oracle Notifier Helper

Source: https://github.com/steipete/oracle/blob/main/vendor/oracle-notifier/README.md

Builds the helper app. Set App Store Connect credentials to notarize and staple the ticket. Requires Xcode command line tools and a macOS Developer ID certificate.

```bash
cd vendor/oracle-notifier
# Optional: notarize by setting App Store Connect key credentials
export APP_STORE_CONNECT_API_KEY_P8="$(cat AuthKey_XXXXXX.p8)" # with literal newlines or \n escaped
export APP_STORE_CONNECT_KEY_ID=XXXXXX
export APP_STORE_CONNECT_ISSUER_ID=YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY
./build-notifier.sh
```

--------------------------------

### Oracle CLI Usage: High-Reasoning (Opus) with Files Report

Source: https://github.com/steipete/oracle/blob/main/docs/anthropic.md

Example of using the Oracle CLI with the Claude 4.1 Opus model for risk analysis, including a files report.

```bash
oracle -m claude-4.1-opus --files-report --prompt "Analyze risk register" --file docs/risk.md
```

--------------------------------

### Run Live OpenAI Tests

Source: https://github.com/steipete/oracle/blob/main/AGENTS.md

Execute live OpenAI tests using Vitest. Requires a real OPENAI_API_KEY. The gpt-5-pro model can take approximately 10 minutes to run.

```bash
ORACLE_LIVE_TEST=1 pnpm vitest run tests/live/openai-live.test.ts
```

--------------------------------

### Manage ChatGPT Project Sources

Source: https://github.com/steipete/oracle/blob/main/docs/browser-mode.md

Commands for interacting with ChatGPT Project Sources. Use 'add' to append files, 'list' to view current sources, and '--dry-run' to preview changes without modifying ChatGPT.

```bash
# Preview the upload plan without touching ChatGPT
oracle project-sources add \
  --chatgpt-url "https://chatgpt.com/g/g-p-example/project" \
  --browser-manual-login \
  --file docs/architecture.md \
  --dry-run
```

```bash
# List current sources
oracle project-sources list \
  --chatgpt-url "https://chatgpt.com/g/g-p-example/project" \
  --browser-manual-login
```

```bash
# Append files to the Sources tab
oracle project-sources add \
  --chatgpt-url "https://chatgpt.com/g/g-p-example/project" \
  --browser-manual-login \
  --file docs/architecture.md docs/decisions.md
```

--------------------------------

### Cursor MCP Configuration

Source: https://github.com/steipete/oracle/blob/main/docs/agents.md

Configure Oracle for Cursor by creating a `.cursor/mcp.json` file. This allows Cursor to use Oracle via its MCP integration. Alternatively, use the one-click install link.

```json
{
  "oracle": {
    "command": "oracle-mcp",
    "args": []
  }
}
```

--------------------------------

### Configure npm Authentication

Source: https://github.com/steipete/oracle/blob/main/docs/RELEASING.md

Set up npm authentication for publishing. This involves creating a token with write access and bypassing 2FA, then configuring npm to use it.

```bash
export NPM_TOKEN=...
```

```bash
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
```

--------------------------------

### Create Oracle Session with Slug

Source: https://github.com/steipete/oracle/blob/main/skills/oracle/SKILL.md

When starting a new Oracle session, use the `--slug` option to assign a human-readable name to the session ID, making it easier to manage and recall.

```bash
oracle --slug "<3-5 words>"
```

--------------------------------

### Generic CLI Usage: Bundle on Clipboard

Source: https://github.com/steipete/oracle/blob/main/docs/agents.md

Use this command when the agent has shell access for a simple hand-off. The bundle is rendered and copied to the clipboard, allowing manual pasting into a Pro model. No keys or MCP are required.

```bash
oracle --render --copy -p "$TASK" --file "$RELEVANT_FILES"
```

--------------------------------

### Manual Paste Fallback (Render and Copy)

Source: https://github.com/steipete/oracle/blob/main/skills/oracle/SKILL.md

Renders the bundled prompt and files into markdown format and copies it to the clipboard. Use this as a fallback when direct browser or API execution is not feasible.

```bash
npx -y @steipete/oracle --render --copy -p "<task>" --file "src/**"
```

--------------------------------

### Run Oracle in Gemini Web (Cookie) Mode

Source: https://github.com/steipete/oracle/blob/main/docs/gemini.md

Utilize Gemini web mode for cookie-based interactions with gemini.google.com. This mode does not require an API key. Examples include text generation, deep thinking, and image generation/editing.

```bash
# Text run
oracle --engine browser --model gemini-3.5-flash --prompt "Say OK."
```

```bash
# Deep Think browser run (manual-login profile recommended on macOS)
oracle --engine browser --browser-manual-login \
  --model gemini-3-deep-think \
  --prompt "Think carefully, then answer in one paragraph."
```

```bash
# Generate an image (writes an output file)
oracle --engine browser --model gemini-3.1-pro \
  --prompt "a cute robot holding a banana" \
  --generate-image out.jpg --aspect 1:1
```

```bash
# Edit an image (input via --edit-image, output via --output)
oracle --engine browser --model gemini-3.1-pro \
  --prompt "add sunglasses" \
  --edit-image in.png --output out.jpg
```

--------------------------------

### Run Oracle Preflight Check

Source: https://github.com/steipete/oracle/blob/main/docs/refactor/ux.md

Use `oracle --preflight` to perform a preliminary check of models and prompt configurations before a full run.

```sh
oracle --preflight --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro -p "..."
```

--------------------------------

### Configure Thinking Time for Browser Mode

Source: https://github.com/steipete/oracle/blob/main/docs/mythical-pro-agents.md

Sets the thinking time for Pro models in browser mode. Use `--browser-thinking-time` with levels like `light`, `standard`, `extended`, or `heavy` to adjust model processing duration. This example targets specific files for refactoring.

```bash
oracle --engine browser --model gpt-5.5-pro \
  --browser-thinking-time extended \
  -p "Refactor this hot path" --file "src/render/**"
```

--------------------------------

### Run GPT-5.5 with File Attachment

Source: https://github.com/steipete/oracle/blob/main/docs/manual-tests.md

Test GPT-5.5 with a file attachment. Ensure upload logs show 'Attachment queued' and the response explicitly references the file content.

```bash
pnpm run oracle -- --engine browser --model gpt-5.5 --prompt "Summarize the key idea from the attached note" --file /tmp/browser-md.txt
```

--------------------------------

### Run Deep Research with GPT-5.5 Pro

Source: https://github.com/steipete/oracle/blob/main/docs/mythical-pro-agents.md

Initiates deep research using the browser engine with GPT-5.5 Pro. Specify the research topic and enable deep research mode. The report will be saved to a local file.

```bash
oracle --engine browser --model gpt-5.5-pro \
  --browser-research deep \
  -p "Survey approaches for embedded vector search in a Rust app, with citations"
```

--------------------------------

### Show Oracle CLI Help

Source: https://github.com/steipete/oracle/blob/main/skills/oracle/SKILL.md

Displays the help message for the Oracle CLI. Use this once per session to understand available commands and options.

```bash
npx -y @steipete/oracle --help
```

--------------------------------

### Run GPT-5.5 Simple Prompt Test

Source: https://github.com/steipete/oracle/blob/main/docs/manual-tests.md

Execute a simple prompt with the GPT-5.5 model in browser engine mode. Expect two markdown bullet points without file or search references. Note the session ID for auditing.

```bash
pnpm run oracle -- --engine browser --model gpt-5.5 --prompt "Give me two short markdown bullet points about tables"
```

--------------------------------

### Submit Prompt and Switch Model with Oracle

Source: https://github.com/steipete/oracle/blob/main/docs/manual-tests.md

Submits a multi-line prompt to the Oracle CLI using the browser engine and switches to GPT-5.5. Verifies prompt submission and model selection logs.

```bash
pnpm run oracle -- --engine browser --model gpt-5.5 \
  --prompt "Line 1\nLine 2\nLine 3"
```

--------------------------------

### Run GPT-5.5 Instant Smoke Test

Source: https://github.com/steipete/oracle/blob/main/docs/manual-tests.md

Test the GPT-5.5 Instant model with a simple prompt. Expect a near-instant response without a thinking spinner. Verify the composer pill indicates the 'Instant' row.

```bash
pnpm run oracle -- --engine browser --model gpt-5.5-instant --prompt "Give me two short markdown bullet points about tables"
```

--------------------------------

### Browser Run

Source: https://github.com/steipete/oracle/blob/main/README.md

Executes a command in the browser engine, opening ChatGPT without requiring an API key. Useful for interactive walkthroughs of UI smoke tests.

```bash
npx -y @steipete/oracle --engine browser -p "Walk through the UI smoke test" --file "src/**/*.ts"
```

--------------------------------

### Launch Oracle CLI Server

Source: https://github.com/steipete/oracle/blob/main/README.md

Launch the Oracle CLI in server mode on a specified host and port. Requires a token for authentication.

```bash
# Host (signed-in Chrome): launch serve
oracle serve --host 0.0.0.0:9473 --token secret123
```

--------------------------------

### Run Live API Smoke Tests (Standard)

Source: https://github.com/steipete/oracle/blob/main/docs/testing.md

Execute live API smoke tests, excluding OpenAI pro. Requires setting ORACLE_LIVE_TEST and OPENAI_API_KEY environment variables.

```bash
ORACLE_LIVE_TEST=1 OPENAI_API_KEY=… pnpm test:live
```

--------------------------------

### Run Write-Output Live Test

Source: https://github.com/steipete/oracle/blob/main/docs/manual-tests.md

Executes a live test for write-output functionality. Expects a temp markdown file to be created with specific content.

```bash
ORACLE_LIVE_TEST=1 OPENAI_API_KEY=<real key> pnpm vitest run tests/live/write-output-live.test.ts --runInBand
```

--------------------------------

### Multi-model Fan-out with Partial Success

Source: https://github.com/steipete/oracle/blob/main/docs/multimodel.md

Execute a prompt across multiple models, allowing partial success if some models fail. Outputs can be written to a specified file.

```bash
oracle \
  --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro \
  --allow-partial \
  --write-output /tmp/panel.md \
  -p "Compare these options and recommend one."
```

--------------------------------

### Copy Bundle to ChatGPT

Source: https://github.com/steipete/oracle/blob/main/README.md

Use this command to copy a bundle of code to ChatGPT for review. It renders the output and copies it to the clipboard.

```bash
npx -y @steipete/oracle --render --copy -p "Review the TS data layer for schema drift" --file "src/**/*.ts,*/*.test.ts"
```

--------------------------------

### Build Project Artifacts

Source: https://github.com/steipete/oracle/blob/main/docs/RELEASING.md

Ensure the project's distribution files are up-to-date before packaging. This command generates the necessary build output in the `dist/` directory.

```bash
pnpm run build
```

--------------------------------

### Publish to npm

Source: https://github.com/steipete/oracle/blob/main/docs/RELEASING.md

Publish the package to the npm registry. Use the `--tag` option to specify whether it should be the `latest` or `legacy` version. Two-factor authentication (OTP) is required.

```bash
npm publish --access public --tag <legacy|latest>
```

--------------------------------

### Configure Oracle for Edge with Cookie Sync via CLI

Source: https://github.com/steipete/oracle/blob/main/docs/chromium-forks.md

This command launches Oracle, points it to Microsoft Edge, and specifies the location of the Edge `Cookies` SQLite database for session synchronization. It also sets a prompt for summarizing release notes.

```bash
oracle --engine browser \
  --browser-chrome-path "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" \
  --browser-cookie-path "$HOME/Library/Application Support/Microsoft Edge/Profile 1/Cookies" \
  --prompt "Summarize the release notes"
```

--------------------------------

### Generic CLI Usage: Dry Run JSON Preview

Source: https://github.com/steipete/oracle/blob/main/docs/agents.md

Inspect the resolved bundle before sending it to a Pro model for autonomous dry-runs. This helps preview the bundle and avoid unnecessary model usage.

```bash
oracle --dry-run json --model gpt-5.5-pro -p "$TASK" --file "$RELEVANT_FILES"
```

--------------------------------

### Token/Cost Sanity Check with File Report

Source: https://github.com/steipete/oracle/blob/main/skills/oracle/SKILL.md

Performs a dry run to estimate token usage and costs, including a report of files that will be bundled. Helps in managing resource consumption.

```bash
npx -y @steipete/oracle --dry-run summary --files-report -p "<task>" --file "src/**"
```

--------------------------------

### Run GPT-5.5 with Verbose File Attachment

Source: https://github.com/steipete/oracle/blob/main/docs/manual-tests.md

Test GPT-5.5 with a file attachment in verbose mode. Verify verbose logs show attachment upload and the answer matches file data.

```bash
pnpm run oracle -- --engine browser --model gpt-5.5 --prompt "Use the attachment to report current CPU and memory figures" --file /tmp/browser-report.txt --verbose
```