DOCSEARCHbyAlgolia
Submit Docs

Oracle CLI

repository·main·Indexed 25 days ago

https://github.com/steipete/oracle

A CLI wrapper and tool for bundling prompts and local files into context-rich packages for AI models. It supports API and browser automation engines for models including GPT-5.x, Claude, and Gemini. Features include multi-model advisory panels, session management, MCP server integration, and a browser mode for automating ChatGPT without API keys.

Tokens
58.4K
Snippets
127
Records
374
Agent score
85%

What's inside Oracle

  1. Run Oracle without installing

    main

    You can run Oracle on demand using npx or pnpx. This is useful for CI, ad-hoc scripts, or when you want to avoid a global binary installation. For CI environments, it is recommended to pin the version (e.g., @steipete/oracle@0.12.1) to cache the package and avoid re-downloading on every job.

    npx -y @steipete/oracle --help
# or
    pnpx @steipete/oracle --help

  2. Perform multi-model cross-checks

    main

    Oracle can query multiple models simultaneously to cross-check assumptions. It aggregates cost and token usage per model and can be configured to keep successful answers even if one provider fails due to auth or quota issues.

    Use oracle doctor --providers to check routing readiness before running a multi-model command.

    # Check provider readiness
oracle doctor --providers --models gpt-5.5-pro,gemini-3-pro,claude-4.6-sonnet

# Run cross-check across multiple models
oracle -p "Cross-check the data layer assumptions" \
  --models gpt-5.5-pro,gemini-3-pro,claude-4.6-sonnet \
  --allow-partial --write-output /tmp/oracle-panel.md \
  --file "src/**/*.ts"

  3. Follow up on an existing session

    main

    You can continue a saved ChatGPT browser conversation or an OpenAI/Azure Responses API session by providing a session ID, a slug, or a resp_... response ID via the --followup flag.

    oracle --followup <id> -p "Re-evaluate with these files" \
  --file "src/migrations/**"

  4. Set up macOS Browser Mode

    main

    Browser mode automates your Chrome browser to use ChatGPT without API keys. This is useful for accessing models like GPT-5.5 Pro directly through the web interface.

    First-time login

    Run this command once to create a private automation profile and log into ChatGPT. The browser will stay open so you can complete the login process. Use --browser-keep-browser to prevent it from closing immediately and --browser-input-timeout 120000 to allow 2 minutes for manual entry.

    oracle --engine browser --browser-manual-login \
  --browser-keep-browser --browser-input-timeout 120000 \
  -p "HI"

    Subsequent runs

    Once logged in, use the following command structure for future runs. The --browser-auto-reattach-* flags help handle redirects during page loads.

    oracle --engine browser --browser-manual-login \
  --browser-auto-reattach-delay 5s \
  --browser-auto-reattach-interval 3s \
  --browser-auto-reattach-timeout 60s \
  -p "your prompt"
    oracle --engine browser --browser-manual-login \
  --browser-keep-browser --browser-input-timeout 120000 \
  -p "HI"

  5. Use Remote Browser Mode with oracle serve

    main

    For reliable shared-agent setups or when using a signed-in Chrome instance with remote debugging, you can host a browser service and connect to it from a client.

    1. On the Host (machine with signed-in Chrome): Launch the server.
    2. On the Client: Target the host using --remote-host and --remote-token.
    # Host (signed-in Chrome): launch serve
oracle serve --host 0.0.0.0:9473 --token secret123

# Client: target that host
oracle --engine browser --remote-host 192.168.1.10:9473 --remote-token secret123 -p "Run the UI smoke" --file "src/**/*.ts"

  6. Use Browser Mode with Oracle

    main

    The --engine browser flag allows Oracle to route prompt bundles through web interfaces instead of direct APIs. It supports three execution paths:

    1. ChatGPT launcher mode (GPT-* models): Oracle launches its own Chrome instance and drives the ChatGPT web UI via CDP.
    2. ChatGPT attach-running mode (GPT-* models): Oracle attaches to an existing local Chrome session (via remote debugging) and opens a dedicated tab.
    3. Gemini web mode (Gemini models): Communicates directly with gemini.google.com using signed-in Chrome cookies.

    If --engine is omitted, Oracle follows this priority: ORACLE_ENGINE environment variable, then the engine value in your configuration files (e.g., .oracle/config.json or ~/.oracle/config.json). It defaults to api if OPENAI_API_KEY is present, falling back to browser otherwise.

    Use --preview with browser mode to render the composed prompt and see which files would be uploaded/inlined without actually launching Chrome.

    oracle --engine browser

  8. Run ChatGPT Deep Research

    main

    Use --browser-research deep for tasks requiring broad web discovery, source comparison, or cited reports.

    Note: Deep Research is browser-only and cannot be combined with --browser-follow-up. If a session times out during research, use oracle session <id> --render to recover the report from the existing tab.

    Completed reports are saved as deep-research-report.md in the session artifacts directory.

    oracle --engine browser \
  --browser-manual-login \
  --browser-research deep \
  -p "Research the current browser support for WebGPU in enterprise-managed Chrome and cite sources."

  9. Configure OpenRouter for Oracle

    main

    To use OpenRouter, set the OPENROUTER_API_KEY environment variable. If no other provider keys (like OPENAI_API_KEY) are present, Oracle will automatically route requests to https://openrouter.ai/api/v1.

    For attribution, it is recommended to also set OPENROUTER_REFERER and OPENROUTER_TITLE. These are forwarded as HTTP-Referer and X-Title headers respectively.

    export OPENROUTER_API_KEY="sk-or-..."
# Optional but recommended for attribution:
export OPENROUTER_REFERER="https://your-app.example"
export OPENROUTER_TITLE="Oracle CLI"

  10. Use Claude models in the Oracle CLI

    main

    You can invoke Claude models using the --model or --models flags. The following model IDs and aliases are available:

    • claude-4.6-sonnet (Alias: sonnet)
    • claude-4.1-opus (Alias: opus)

    Important Limitations:

    • Background runs are disabled: Even if you use the --background flag, Claude runs will stream normally and will not run in the background.
    • Search is disabled: The --search flag and web_search_preview tool are ignored for Claude models.

  11. Understand Oracle engine selection logic

    main

    Oracle determines which engine (API or Browser) to use based on the following priority order:

    1. The --engine flag provided in the command.
    2. The engine setting in the effective configuration (starting from ~/.oracle/config.json and layering project-specific .oracle/config.json files from parent folders down to the current directory).
    3. The presence of a supported API key (e.g., OPENAI_API_KEY) in the environment (switches to API mode).
    4. Default to browser mode.

    Note: The Browser engine supports ChatGPT (GPT-* models) and Gemini (Gemini-*); all other models require API mode.

  12. Configure Oracle via JSON5 configuration files

    main

    Oracle uses JSON5 for configuration, allowing comments and trailing commas. It supports two levels of configuration:

    1. User Configuration: Located at ~/.oracle/config.json. This is the primary place for machine-local settings, secrets, and provider routing.
    2. Project Configuration: Located at .oracle/config.json within your project directory. Oracle discovers these by searching upward from your working directory to your home directory. Project configs are merged into the user config (nested objects merge, scalars/arrays replace).

    Important Security Note: Project-level configs (.oracle/config.json) are restricted to workflow defaults. They cannot set sensitive or machine-specific fields like apiBaseUrl, modelOverrides, azure, browser.remoteHost, browser.remoteToken, browser.chromePath, or browser.chromeCookiePath. These must be kept in your user config or environment variables.

    // ~/.oracle/config.json example
{
  engine: "api",
  model: "gpt-5.5-pro",
  search: "on",
  notify: {
    enabled: true,
    sound: false,
    muteIn: ["CI", "SSH"]
  },
  browser: {
    chromeProfile: "Default",
    chatgptUrl: "https://chatgpt.com/"
  }
}