Quickstart

Ten minutes, one terminal, a working Octolens workspace at the end. Install the CLI first if you have not (Install & login).

No Octolens account yet? The CLI creates the workspace itself:

octolens signup

The browser completes the signup and the CLI ends authenticated; on a box with no browser at all, octolens signup --headless runs the whole flow in the terminal with an emailed code. Both modes — and the Agents plan such workspaces start on — are on Signup & the Agents plan.Already have a workspace? Log in instead:

octolens login

On a headless box, use an API key — run octolens login --with-key ak_live_xxx or set OCTOLENS_API_KEY; details on Install & login.

Run your first search

One command, no setup — a one-time, AI-scored search across the platforms enabled for your workspace:

octolens search "your brand" --days 7

Results are ranked by relevance and never mix into your mentions feed. On the Agents plan searches draw on a lifetime allowance — Signup & the Agents plan explains the numbers and the upgrade path.

Initialize your workspace

New workspace? The guided onboarding builds it from the terminal — company profile, the keywords you want monitored, noise filters and your first feed:

octolens init

It is safe on an existing workspace too: it reports what is already set up and only offers the missing steps. See Initialize a workspace for the whole flow.

Check who you are

Confirm the workspace and the credential’s scope before doing anything else — this is also the preflight your scripts should run:

octolens whoami

Read your mentions

The ten newest mentions Octolens has collected for you:

octolens mentions list --limit 10

Narrow it while you explore — add --source reddit --sentiment negative for the classic “what is bothering people” view.

Triage one mention

Take a sourceId from the list you just printed (the examples below use a placeholder), inspect the mention, then act on it:

octolens mentions get reddit_t3_1abc234
octolens mentions update reddit_t3_1abc234 --relevance not_relevant
octolens mentions engage reddit_t3_1abc234 --engaged true

mentions update corrects the AI’s relevance or sentiment call; mentions engage marks that you have responded to the conversation.

Save a feed

A feed is a saved filter over your mention stream. Describe the one you want in plain language and let the AI build the filter:

octolens feeds create --name Pricing --ai "posts about pricing this week" --yes

From now on octolens mentions list --feed 42 (use the id the create printed) reads that slice directly, and octolens feeds watch follows your mentions live in the terminal.

Read the numbers

Mention volume over time, as a sparkline plus per-bucket counts:

octolens analytics volume

octolens analytics sentiment and octolens analytics keywords cut the same data by tone and by term.

Scripting what you just did

Everything above works headlessly: add --json and each command emits exactly one JSON document on stdout (Output modes defines all three renderings). Every command also accepts the global flags, generated here from the CLI’s own contract manifest:

Flag	Type	Required (headless)	Description
`--base-url`	`string`	no	Override the app base URL (env OCTOLENS_BASE_URL) — one resolution feeds the REST API base, —web pages, billingUrl, and OAuth handoffs; defaults to https://app.octolens.com
`--json`	`boolean`	no	Output pure machine-readable JSON (no decoration)
`--timeout`	`integer`	no	Per-request deadline in seconds (default 30). When it expires the request is aborted and the run exits 1 with a REQUEST_TIMEOUT (504) envelope instead of blocking — EXCEPT when a state-changing request had already returned its 2xx status line, where the write was accepted and may have landed, so the answer is RESPONSE_LOST (502, exit 10): verify with the matching list/get before retrying. Overrides the longer per-operation defaults too. Also governs login’s out-of-band browser-handoff wait (—no-browser included; default 180s there), where expiry exits 2 LOGIN_TIMEOUT instead.
`--transport`	`rest` (the only value)	no	Force the backend transport: rest = the public REST v2 API (the only one in this build)
`--verbose`	`boolean`	no	Show diagnostic logs on stderr (same as OCTOLENS_DEBUG=1): one line per REST request — method, path, status, duration — plus retry/backoff events
`--web`	`boolean`	no	Open this resource’s page in the Octolens web app instead of running the command (prints the URL; only a TTY spawns the browser)

When scripting, branch on exit codes (or the --json error envelope’s code), never on message text:

Exit	Name	Meaning
`0`	`OK`	success
`1`	`UNEXPECTED`	unexpected
`2`	`USAGE`	usage
`3`	`AUTH`	auth
`4`	`NOT_FOUND`	not found
`5`	`PERMISSION`	permission/scope
`6`	`LIMIT`	plan/limit
`7`	`RATE_LIMITED`	rate-limited
`8`	`CANCELLED`	cancelled (a human aborted a prompt with EOF/Ctrl-C)
`9`	`FAILED`	the command ran and the operation did not succeed at its target
`10`	`INDETERMINATE`	a write was accepted and its answer lost — verify, do not retry

The full rules live on The —json contract and The error envelope.

Get started

Contract

Commands

Concepts

Guides

Scripting & agents

Scripting what you just did

​Scripting what you just did

Scripting what you just did