Skip to main content
The CLI’s guarantees — one JSON document on stdout, a frozen exit map, bounded runs, no prompts — exist precisely so that an AI agent can drive Octolens the way it drives git or gh: from a shell, with no SDK, no schema discovery, and failure modes it can branch on. This page is how to hand those guarantees to your agent.

​
An agent can start from zero

An agent does not need a pre-provisioned account: octolens signup --headless creates a workspace end to end from a headless shell — email, emailed 6-digit code, company domain — as a resumable two-step under --json, and finishes with a stored, validated API key. From there octolens search "your brand" --json returns AI-scored results with no keyword setup first. The flow, the Agents-plan allowance behind it, the quota headers a client can self-throttle on, and the UPGRADE_REQUIRED wall (exit 6, with upgradeUrl/upgradeCommand in the envelope, answered by octolens upgrade) are all on Signup & the Agents plan.

​
Install the Agent Skill

The fastest path is the official Octolens Agent Skill — a drop-in package of expertise that teaches Claude Code, Cursor, and other compatible agents which commands to reach for, how to filter mentions, and the gotchas to avoid:
The skill activates on its own whenever a task involves Octolens. It covers the two surfaces an agent cannot introspect — the CLI’s command surface and the REST v2 endpoint surface — and tells the agent which to prefer when. With it installed, you can ask for outcomes (“pull last week’s negative Reddit mentions and summarize the top complaints”) instead of dictating commands.

​
llms.txt

Two machine-readable summaries exist for agents that read docs rather than install skills:
  • This docs site publishes an llms.txt index at octolens.com/docs/llms.txt, so an agent can discover every page here — including the contract pages — without scraping HTML.
  • The npm package ships one inside the tarball (node_modules/octolens/llms.txt) alongside COMMANDS.md, the generated command reference — readable offline, always matching the installed version. octolens help <command> prints the same contract from the binary itself.

​
CLI, MCP, or REST?

Octolens has three programmable surfaces. They call the same platform; pick by where the caller runs: The CLI is a client of the same REST v2 API, but it adds the guarantees raw endpoints do not have: the frozen exit-code map you can branch on instead of parsing message text, exactly one JSON document on stdout under --json, automatic rate-limit retry, a per-request --timeout that guarantees termination, and name-to-id resolution (--keyword 'acme corp' instead of a lookup call first). For an agent that can run shell commands, the CLI is the highest-leverage surface — the Agent Skill makes the same recommendation.

​
Ground rules for an agent loop

Whether or not the skill is installed, an agent driving the CLI should follow four rules — each backed by a guarantee on The agent contract:
  1. Always pass --json. It guarantees pure output and forces non-interactive mode, so the run can never hang on a prompt — missing input fails fast with exit 2 naming the flags to pass.
  2. Verify credentials once, with octolens whoami --json. It reports the workspace, auth source and key scope — do not scrape config files. Branch on the auth family of codes, not one code (Handling failure in scripts).
  3. Branch on exit codes and error.code, never on message text. The codes are frozen; the wording is not.
  4. Never auto-retry exit 10. The write may have landed — verify with the matching list/get first. A generic retry-on-failure policy must carve this one exit out.
For live streams, add the tail-only flag — octolens feeds watch --backlog none --json gives an agent a forward-only stream with no pre-existing backlog to filter out (Watch a feed live).

​
Recipes to hand your agent

The pages in this section are written to be pasted into an agent’s context as much as read by you: the agent contract states the invariants, the jq cookbook gives working projections, and Handling failure in scripts gives the branch logic. An agent that has those three pages — or the skill, which distills them — will drive Octolens correctly on the first try.