CLI Reference

Every AgentOps command, organized by workflow. All commands accept -c, --config <path> to point at a specific AgentOps config file (default: .agentops/config.yaml in the project). Global flags: -v, --version.

Quick verification path

After install, these commands prove the local workspace, hooks, and account path are wired correctly:

agentops --version
agentops doctor
agentops hooks status
agentops status

Expected success:

  • agentops --version prints the installed version.
  • agentops doctor reports the config, database, and CLI as healthy.
  • agentops hooks status reports installed hooks as OK; missing hooks include the repair command.
  • agentops status shows the player dashboard when logged in. If it says you are not authenticated, run agentops login.

Setup

  • agentops init — initialize the local AgentOps workspace. Flags: --force (overwrite existing config)
  • agentops install — initialize AgentOps and install local hook wrappers in one step. Flags: --force
  • agentops doctor — check the local AgentOps workspace health

Hooks

  • agentops hooks install <claude|codex|gemini> — install a local hook wrapper. Flags: --force (overwrite existing wrappers)
  • agentops hooks status — check whether the local hooks and build are ready
  • agentops hooks test <claude|codex|gemini> — test hook payload parsing fixtures
  • agentops hooks claude — read a Claude hook payload from stdin and store it locally (called by the wrapper, not by you)
  • agentops hooks codex — read a Codex hook payload from stdin and store it locally (called by the wrapper)
  • agentops hooks gemini — read a Gemini hook payload from stdin and store it locally (called by the wrapper)
  • agentops opencode install — install the local OpenCode plugin entrypoint. Flags: --force
  • agentops opencode status — show the local OpenCode plugin status
  • agentops opencode hook <phase> — read an OpenCode hook payload from stdin and normalize it (called by the plugin; phases: tool.execute.before, tool.execute.after, shell.env, event)

Running and observing

  • agentops run <command...> — run any command through the local AgentOps wrapper
  • agentops report — print a local token, cache, and intelligence report. Flags: --cost (include estimated cost breakdown)
  • agentops commands — list recent recorded commands. Flags: --last <n> (default 20)
  • agentops top-waste — show the highest token-burning commands
  • agentops pipeline — show data pipeline status and recorded commands. Flags: --inspect (show last recorded commands), --json

Scoring and leaderboard

  • agentops score — show the AgentOps score for your last agent session. Flags: -s, --session <id>
  • agentops login — sign in with Google to enable leaderboard submissions. Flags: --force (re-authenticate)
  • agentops submit — submit your session score to the global leaderboard. Flags: -s, --session <id>
  • agentops leaderboard — view the global leaderboard. Flags: --period <daily|weekly|monthly|alltime> (default weekly), --agent <agent>, --category <overall|cache|savings|waste|volume> (default overall), --project <name>, --team <code>, --html, -o, --output <path>
  • agentops status — show your player dashboard: level, XP, streak, challenges
  • agentops achievements — show all achievement badges with lock status

Sharing

  • agentops scorecard — generate a shareable scorecard for your last session. Flags: -s, --session <id>, -o, --output <path>, --no-open, -t, --theme <name> (default, neon, minimal, retro, matrix, aurora, legendary, gold)
  • agentops dashboard — generate a visual HTML dashboard of your agent cost intelligence. Flags: -o, --output <path>, --no-open
  • agentops wrapped — view your weekly wrapped summary. Flags: -w, --week <weekId> (e.g. 2026-W26), -o, --output <path>, --no-open
  • agentops share — copy your weekly share block to clipboard. Flags: -w, --week <weekId>
  • agentops badge — show your GitHub badge embed snippets
  • agentops profile — view your public profile page. Flags: --feature <id> (pin an achievement), --unfeature <id>, --featured (list featured), --json, --no-open

Plugins

  • agentops plugins — list built-in and installed output plugins with stats. Flags: --available (browse the server catalog), --install <id>, --remove <id>, --info <id>, --sync (force sync with server), --enable <id>, --disable <id>, --json

See Plugins for the plugin authoring guide.

Troubleshooting

Not logged in

Symptoms: agentops status or agentops submit reports an authentication error.

agentops login
agentops status

Expected success: the browser OAuth flow completes and agentops status shows level, XP, streak, and challenges.

Hooks missing

Symptoms: sessions record no commands, agentops report is empty, or agentops hooks status shows MISSING.

agentops hooks install claude   # or codex/gemini
agentops opencode install       # for OpenCode
agentops hooks status

Expected success: the hook you use reports OK. Then run a normal agent session and inspect the last commands:

agentops commands --last 5

Privacy check

Use agentops submit for leaderboard stats only. The submitted payload contains scores, token counts, cache counts, model identifiers, agent kind, project metadata, and CES integers. It does not include source code, prompts, transcripts, raw command output, file paths, or repo internals. See Model Communication and Privacy.

Repo intelligence

  • agentops repo-map — print a compact repository map
  • agentops symbols <name> — search for a symbol and related usages
  • agentops context <topic> — build a compact repo-aware context bundle

Cache

  • agentops cache stats — show cache hit rate, saved tokens, and recent entries
  • agentops cache show <key> — print one cached entry by key
  • agentops cache clear — remove all local cache entries
  • agentops cache enable — enable caching in the local config
  • agentops cache disable — disable caching in the local config

Policy

  • agentops policy init <template> — install a named policy template into local config
  • agentops policy show — show the active local policy configuration
  • agentops policy test <command...> — evaluate a command against the local policy rules

Optimization

  • agentops optimize — analyze patterns and propose optimization rules. Flags: --status (show active rules and measured impact), --apply (auto-approve all proposals), --dry-run (show proposals without saving)
← Plugins FAQ →