opper-cli

Skill version 2026-10-12. This is a locally installed copy and may be out of date. Once per session, fetch https://skills.opper.ai/versions.json and compare its "opper-cli" entry with 2026-10-12. If they differ, read https://skills.opper.ai/opper-cli/SKILL.md and follow that instead of this copy for the rest of the session, and tell the user once that their installed Opper skills are out of date (update with npx skills update, or git pull in a manual clone). Do not edit the installed files. If the fetch fails, continue with this copy.

Sub-skill of opper — start there for discovery and setup guidance. Source: https://github.com/opper-ai/opper-skills/blob/main/opper-cli/SKILL.md

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 the API. 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.

For agent-assisted setup, platform operations, and model tests, prefer the opper-mcp skill. Connecting MCP provides Opper tools; opper launch routes the agent's own inference through Opper. The CLI also delivers application keys privately with opper keys create --project <uuid> --name <name> --output <env-file> — consult opper keys create --help and do not read or print the resulting secret.

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 populated by the device flow. Pick a slot with --key <slot> on any command (default: default); inspect or remove slots with opper config list/get/remove.

opper login handles authentication interactively in the browser, so no key needs to be typed or pasted into a command. For non-browser paths, see opper config --help.

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 list/get/remove`	Inspect or remove auth slots (slots are created by `opper login`).
`call <name> <instructions> [input]`	Run an Opper function. Stdin if `input` omitted; `--model`, `--stream`. Legacy — rides the `/v3/call` surface being sunset; don't build on it (see gotchas).
`functions list/get/delete`	Manage saved functions.
`indexes ...`	Knowledge bases. Being sunset with the knowledge base feature; don't start new work on them.
`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 rides the legacy /v3/call surface, which is being sunset. Fine for a quick ad-hoc poke, but never the pattern to build on or copy into application code — that's a compat chat endpoint with response_format (see the opper-api skill and its references/migration.md).
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.
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
Connecting an agent to Opper tools and testing models	the `opper-mcp` skill
Building Opper into application code (the OpenAI / Anthropic / Google SDKs on `/v3/compat`)	the `opper-api` skill