Skip to main content

​
Install

The octolens CLI is published as the octolens package on npm and runs on Node.js >=20.
Or run it without installing:

​
No account yet? Sign up from the terminal

You do not need an existing workspace to log into — octolens signup creates one and ends with an authenticated CLI, either through a browser handoff or (with --headless) entirely in the terminal via an emailed code. The whole flow, the Agents plan it lands on, and the upgrade path are on Signup & the Agents plan.

​
Sign in from a terminal with a browser

Here is what actually happens: the CLI opens a page on your Octolens deployment (where you are already signed in), that page mints a scoped API key for you, and the key is handed back to the CLI over a one-time localhost callback. The CLI validates the key against the workspace before saving it as a named profile — so a successful octolens login always ends with a credential that is known to work. On a machine where the CLI cannot open a browser itself (SSH boxes, remote containers), use octolens login --no-browser: it prints the authorize URL for you to open anywhere, then waits for the key to arrive. The wait is bounded by the global --timeout, and expiry ends the command with a LOGIN_TIMEOUT error — it always terminates on its own. The flag table below carries the exact bound and exit code. octolens login Arguments Flags

​
API keys for CI, agents and scripts

Headless environments should skip login entirely: set the OCTOLENS_API_KEY environment variable and every command uses it directly. An environment key takes precedence over any stored profile and writes nothing to disk — the full precedence rules are on Auth, profiles & workspaces.
Keys are minted in the app under Settings → API at https://app.octolens.com/me/api. To store a key as a profile on a headless box instead (so you do not have to export it every run), pass it to login:
On a terminal, a bare octolens login --with-key gives you a masked paste prompt, so the key never lands in your shell history.

​
Scopes at a glance

Every credential carries a scope, and the API enforces it server-side:
  • read — list and inspect: mentions, feeds, keywords, analytics.
  • write — everything read allows, plus mutations: triage mentions, create feeds, manage keywords and notifications.
  • admin — everything write allows, plus workspace administration: members, organization settings, billing.
The browser login mints the scope you ask for — the --scope row in the flag table above carries the choices and the default. Check what a credential can do before using it: octolens whoami reports the workspace and the credential’s live scope, so it is the natural preflight in scripts. A read-only key is refused by any mutating command — see Exit codes for how that refusal surfaces. The full ladder and the per-endpoint requirements are on API keys & scopes, and the credential resolution rules on Auth preflight.

​
Plan requirements

API access — which is what the CLI uses — requires a workspace with an active plan; every current Octolens plan includes it. A workspace whose plan has lapsed (for example an expired free trial) gets a FORBIDDEN refusal naming the upgrade path until a plan is active again.

​
Next steps

  • New workspace? Run octolens init — the guided onboarding sets up your company profile, keywords, filters and first feed from the terminal.
  • Then take the Quickstart for your first ten minutes of real usage.

​
Getting help