> ## Documentation Index > Fetch the complete documentation index at: https://octolens.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Install & login > Install the octolens CLI from npm, sign in through the browser or with an API key, and understand scopes and plan requirements. ## Install The `octolens` CLI is published as the `octolens` package on npm and runs on Node.js `>=20`. ```bash theme={null} npm install -g octolens octolens version ``` Or run it without installing: ```bash theme={null} npx octolens version ``` ## 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](/docs/cli/agents). ## Sign in from a terminal with a browser ```bash theme={null} octolens login ``` 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** | Argument | Type | Required | Description | | -------- | -------- | -------- | ----------------------------------------------------------- | | `KEY` | `string` | optional | API key to save (with --with-key); prefer the masked prompt | **Flags** | Flag | Type | Required (headless) | Description | | -------------- | ------------------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--no-browser` | `boolean` | no | Print the authorize URL instead of opening a browser, then wait for the key to arrive out of band. The wait is time-bounded: the global --timeout governs it (default 180s without the flag), and expiry exits 2 with a LOGIN\_TIMEOUT envelope — the process always terminates on its own | | `--profile` | `string` | no | Name to store this login under | | `--scope` | enum: `read`, `write`, `admin` | no | Scope to mint during the browser handoff (default: `write`) | | `--with-key` | `boolean` | no | Authenticate with an API key (headless boxes) instead of the browser — create one at [https://app.octolens.com/me/api](https://app.octolens.com/me/api) | ## API keys for CI, agents and scripts [Headless](/docs/cli/concepts/output-modes#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](/docs/cli/concepts/auth-profiles). ```bash theme={null} OCTOLENS_API_KEY=ak_live_xxx octolens whoami --json ``` Keys are minted in the app under **Settings → API** at [https://app.octolens.com/me/api](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: ```bash theme={null} octolens login --with-key ak_live_xxx ``` 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](/docs/cli/contract/exit-codes) for how that refusal surfaces. The full ladder and the per-endpoint requirements are on [API keys & scopes](/docs/cli/concepts/keys-scopes), and the credential resolution rules on [Auth preflight](/docs/cli/contract/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`](/docs/cli/init) — the guided onboarding sets up your company profile, keywords, filters and first feed from the terminal. * Then take the [Quickstart](/docs/cli/quickstart) for your first ten minutes of real usage. ## Getting help * Product and pricing: [https://octolens.com](https://octolens.com) * Report a problem: [https://github.com/octolens/octolens/issues](https://github.com/octolens/octolens/issues)