> ## 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. # Quickstart > Your first ten minutes with the octolens CLI — sign up or log in, run your first search, triage a mention, save a feed and read the numbers. Ten minutes, one terminal, a working Octolens workspace at the end. Install the CLI first if you have not ([Install & login](/docs/cli/install)). No Octolens account yet? The CLI creates the workspace itself: ```bash theme={null} 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](/docs/cli/agents). Already have a workspace? Log in instead: ```bash theme={null} octolens login ``` On a [headless](/docs/cli/concepts/output-modes#headless) box, use an API key — run `octolens login --with-key ak_live_xxx` or set `OCTOLENS_API_KEY`; details on [Install & login](/docs/cli/install). One command, no setup — a one-time, AI-scored search across the platforms enabled for your workspace: ```bash theme={null} 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](/docs/cli/agents) explains the numbers and the upgrade path. New workspace? The guided onboarding builds it from the terminal — company profile, the keywords you want monitored, noise filters and your first feed: ```bash theme={null} 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](/docs/cli/init) for the whole flow. Confirm the workspace and the credential's scope before doing anything else — this is also the preflight your scripts should run: ```bash theme={null} octolens whoami ``` The ten newest mentions Octolens has collected for you: ```bash theme={null} octolens mentions list --limit 10 ``` Narrow it while you explore — add `--source reddit --sentiment negative` for the classic "what is bothering people" view. Take a sourceId from the list you just printed (the examples below use a placeholder), inspect the mention, then act on it: ```bash theme={null} 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. 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: ```bash theme={null} 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. Mention volume over time, as a sparkline plus per-bucket counts: ```bash theme={null} 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](/docs/cli/concepts/output-modes#headless): add `--json` and each command emits exactly one JSON document on stdout ([Output modes](/docs/cli/concepts/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](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](/docs/cli/contract/json-output) and [The error envelope](/docs/cli/contract/error-envelope).