#Homebrew (macOS / Linux)
brew install steipete/tap/oracleThe tap also publishes the oracle-notifier macOS helper used by long-running browser runs.
#npm / pnpm
npm install -g @steipete/oracle
# or
pnpm add -g @steipete/oracleRequires Node 24 or newer. After install:
oracle --help
oracle --version#Run without installing
npx -y @steipete/oracle --help
pnpx @steipete/oracle --helpnpx is fine for CI, ad-hoc scripts, or when you don't want a global binary on the box. Cache the package in CI by pinning the version (@steipete/oracle@0.11.0) so you don't re-download on every job.
#API keys (optional)
API mode is opt-in and reads keys from the environment. Set whichever providers you'll use:
| Provider | Env var | Models |
|---|---|---|
| OpenAI | OPENAI_API_KEY | GPT-5.x, GPT-5.x Pro, GPT-5.1 Codex |
| Azure OpenAI | AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, ..._DEPLOYMENT | Same models, hosted on Azure |
GEMINI_API_KEY | Gemini 3.1 Pro (API-only), Gemini 3 Pro | |
| Anthropic | ANTHROPIC_API_KEY | Claude Sonnet 4.6, Claude Opus 4.1 |
| OpenRouter | OPENROUTER_API_KEY | Any OpenRouter id (e.g. minimax/minimax-m2) |
If no key is set, Oracle defaults to browser mode and drives ChatGPT directly — see Browser Mode for the manual-login flow.
#Where Oracle stores state
| Path | Contents |
|---|---|
~/.oracle/config.json | Defaults (JSON5). See Configuration. |
~/.oracle/sessions/<id>/ | Run logs, bundles, transcripts, generated artifacts |
~/.oracle/cookies.json | (Optional) inline ChatGPT cookies for browser mode |
Override the root with ORACLE_HOME_DIR=/some/path if you'd rather keep state under XDG config or per-project.
#Updating
brew upgrade oracle # Homebrew
npm update -g @steipete/oracleoracle --version reports the current build. Releases land on GitHub Releases with notes copied from the changelog.