Opper CLI

The official Opper CLI, distributed as the npm package @opperai/cli. Source: github.com/opper-ai/cli. Requires Node.js ≥ 20.12.

The CLI is more than a thin wrapper over /v3/call. It also launches coding agents (Claude Code, OpenCode, Codex, Hermes, Pi) with their model traffic routed through Opper, installs bundled skills, and wires AI code editors to Opper.

Install

npm i -g @opperai/cli
opper --version

Authenticate

opper login    # OAuth device flow — recommended
opper whoami   # confirm the active slot

State lives in ~/.opper/config.json as a list of slots, each holding api_key, base_url, and the user metadata returned by the device flow. Pick a slot with --key <slot> on any command (default: default).

Manual key entry (no browser):

opper config add default <your-api-key>
opper config add staging <staging-key> --base-url https://...
opper config list

Resolution at request time: OPPER_API_KEY env var > slot named by --key (or default).

Always use --help — it is the source of truth

Subcommand surface area changes faster than this skill. Before guessing flags or argument order:

opper --help              # top-level command list, grouped by domain
opper <command> --help    # subcommands and flags

Run opper with no args for an interactive menu (Account · Agents · Skills · Opper).

Top-level command groups

Group	What it does
login / logout / whoami	OAuth device flow + slot inspection.
config add/list/get/remove	Manual slot management.
call <name> <instructions> [input]	Run an Opper function. Stdin if input omitted; --model, --stream.
functions list/get/delete	Manage saved functions.
indexes list/get/create/delete/add/query	Knowledge bases (a.k.a. indexes).
models list/create/get/delete	Built-in + custom (LiteLLM-backed) models.
traces list/get/delete	Inspect execution traces.
usage list	Token/cost analytics, optional CSV export.
image generate <prompt>	Generate an image.
agents list / launch <agent>	List and launch coding agents through Opper.
editors list/opencode/continue	Wire AI code editors to Opper.
skills list/install/update/uninstall	Install bundled Opper SKILL.md docs to ~/.claude/skills/ and ~/.codex/skills/.
version	Print CLI version (also --version / -v).

Launching agents through Opper

opper launch <agent> is the headline new feature. Anything after the agent name is forwarded to the agent's CLI verbatim. Each agent is wired in differently — fetch the live README at github.com/opper-ai/cli for the current matrix.

opper agents list             # NAME / DISPLAY / KIND / STATE / CONFIG / COMMAND
opper launch claude           # Claude Code (via ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN)
opper launch opencode         # OpenCode
opper launch codex            # OpenAI Codex
opper launch hermes           # Hermes (isolated HERMES_HOME, leaving your existing ~/.hermes/ unchanged)
opper launch pi               # Pi (pi.dev)
opper launch <agent> --install  # also installs the upstream agent when it is not already present

Under the hood these all route to /v3/compat/... (see the opper-api skill).

Global flags

Flag	Description
--key <slot>	API key slot to use (default: default).
--debug	Verbose diagnostic output.
--no-telemetry	Disable anonymous telemetry.
--no-color	Disable ANSI colors.
-v, --version	Print CLI version.
-h, --help	Show help (grouped by domain).

Non-obvious gotchas

• OPPER_API_KEY env var beats --key. When the env var is set, the --key <slot> flag has no effect. Unset it to use a slot.
• opper call argument order is <function> <instructions> <input> — easy to flip.
• Model identifiers use provider/<id-with-dashes> (e.g. anthropic/claude-sonnet-4-6, anthropic/claude-opus-4-7, openai/gpt-4o) — dashes, not dots, even for versions. Custom models registered with opper models create are LiteLLM-backed. List the live set with opper models list or curl -s https://api.opper.ai/v3/models.
• indexes is the CLI name for knowledge bases. opper indexes add <name> <content> takes content as a positional arg (use - to read from stdin), not a --content flag.
• opper usage list --fields does not accept count. cost and count are always included automatically; valid --fields are total_tokens, prompt_tokens, completion_tokens.
• Skills are installed under ~/.claude/skills/ and ~/.codex/skills/. The Codex install also registers each skill in a managed [[skills.config]] block in ~/.codex/config.toml.

Where to look next

For	Look at
Install, agents matrix, releases, license	github.com/opper-ai/cli
Live argument and flag reference	opper <command> --help
The platform behind the CLI (compat endpoints, models)	the opper-api skill
Building Opper into application code	the opper-sdks skill