install.md

title	Install
description	Install Oracle via Homebrew, npm, or run on demand with npx. Node 24+ required.

Homebrew (macOS / Linux)

brew install steipete/tap/oracle

The 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/oracle

Requires Node 24 or newer. After install:

oracle --help
oracle --version

Run without installing

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

npx 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.12.1) 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
Google	GEMINI_API_KEY	Gemini 3.1 Pro, Gemini 3.5 Flash, Gemini 3.1 Flash-Lite
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/oracle

oracle --version reports the current build. Releases land on GitHub Releases with notes copied from the changelog.