Opper CLI

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.

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

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

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.
• 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