Auth

Flags and arguments below are the contract as the binary states it. The global flags (--json, --timeout, …) apply here too and are documented on Global flags. Error codes are a workspace-global contract, not a per-command one — the taxonomy, and how to read a code that is not in it, is on The error envelope. Authenticate the CLI (browser handoff or API key) 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

Examples

octolens login
octolens login --with-key
octolens login --with-key ak_live_xxx

Returns With --json, stdout carries one JSON document with these fields.

Field	Type	Description
`loggedIn`	boolean	Always `true` — a failed login answers the error envelope instead.
`edition`	enum: `internal`, `customer`	The CLI build edition (same value `version` reports).
`profile`	string \| null	Name of the stored profile this login created or updated.
`workspace`	object \| null	The authenticated workspace (`{organizationId, name, plan}`), when it could be read.
`workspace.organizationId`	string	Organization id.
`workspace.name`	string	Workspace name.
`workspace.plan`	string \| null	Current plan. `null` when none.
`actingAs`	object \| null	Present when this login acts on another workspace (`{orgId, workspace?}`). `null` otherwise.
`baseUrl`	string	The effective app base URL for this login — what the REST transport targets.
`pinnedBaseUrl`	string \| null	The deployment the key was verified against and persisted with the profile. `null` for flows that pin nothing.

Without --json: A terminal prints one confirmation line naming the workspace and profile. Example output:

{
  "loggedIn": true,
  "edition": "customer",
  "profile": "acme",
  "workspace": {
    "organizationId": "org_2abcDEFghij345",
    "name": "Acme",
    "plan": "Pro_v3"
  },
  "actingAs": null,
  "baseUrl": "https://app.octolens.com",
  "pinnedBaseUrl": "https://app.octolens.com"
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE · 8 CANCELLED. The full map is on Exit codes.

`octolens logout`

Remove stored login credentials Flags

Flag	Type	Required (headless)	Description
`--all`	`boolean`	no	Remove every stored profile
`--profile`	`string`	no	Name of the profile to remove

Examples

octolens logout
octolens logout --profile acme
octolens logout --all

Returns With --json, stdout carries one JSON document with these fields.

Field	Type	Description
`loggedOut`	boolean	Always `true` — having nothing to remove is an error (exit 2), not a payload.
`removed`	string[]	Names of the profiles that were removed.
`envCredentialsStillActive`	boolean	`true` when `OCTOLENS_API_KEY`/`OCTOLENS_ORG` are set — logout cannot remove env credentials.
`activeProfile`	null	Always `null` after a logout: another stored login is never silently promoted.
`remainingProfiles`	string[]	Profiles still stored (switch back in with `switch`). Empty when none remain.

Without --json: A terminal prints what was removed and which profiles remain. Example output:

{
  "loggedOut": true,
  "removed": [
    "acme"
  ],
  "envCredentialsStillActive": false,
  "activeProfile": null,
  "remainingProfiles": [
    "globex"
  ]
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE. The full map is on Exit codes. Create an Octolens workspace from the terminal (browser handoff, or —headless email code) Flags

Flag	Type	Required (headless)	Description
`--code`	`string`	no	The 6-digit verification code from the email (requires —signup-id headlessly)
`--domain`	`string`	no	Your company domain (e.g. corp.com) — sets up the workspace profile. Defaults to your email’s domain for work addresses; personal providers (gmail, outlook, yahoo, …) say nothing about your company, so they still require this flag (or the prompt). An explicit —domain always wins.
`--email`	`string`	no	Work email to sign up with (—headless; prompted for interactively when omitted)
`--headless`	`boolean`	no	Sign up entirely in the terminal: a verification code is emailed to you (no browser anywhere in the loop, works over SSH).
`--no-browser`	`boolean`	no	Print the signup 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 SIGNUP_TIMEOUT envelope pointing at the `login --with-key` paste fallback — the process always terminates on its own
`--profile`	`string`	no	Name to store this login under
`--signup-id`	`string`	no	Pending signup id from a previous `signup --headless --email …` run — resume verification without restarting

Examples

octolens signup
octolens signup --no-browser
octolens signup --headless
octolens signup --headless --email you@corp.com --json
octolens signup --headless --signup-id 4f2a… --code 123456 --domain corp.com --json

Returns With --json, stdout carries one JSON document with these fields.

Field	Type	Description
`signedUp`	boolean	`true` when the workspace was created and the profile saved — both the browser handoff and the headless finishing run answer it (the headless step-1 run answers the `false` variant below).
`edition`	enum: `internal`, `customer`	The CLI build edition (same value `version` reports).
`profile`	string \| null	Name of the stored profile this signup created.
`workspace`	object \| null	The freshly created Agents workspace (`{organizationId, name, plan}`) — same shape `login` emits.
`workspace.organizationId`	string	Organization id.
`workspace.name`	string	Workspace name.
`workspace.plan`	string \| null	Current plan — `Agents` for a fresh signup.
`actingAs`	object \| null	Always `null` — a signup never acts on another workspace.
`baseUrl`	string	The effective app base URL for this signup — what the REST transport targets.
`pinnedBaseUrl`	string \| null	The deployment the minted key was verified against and persisted with the profile.

Two modes, one success document. Default (browser handoff): the browser runs the actual signup (Clerk sign-up, domain, workspace creation) and the document reports the credential the handoff delivered and validated. --headless: the minted API key is saved into the profile and never printed — --json carries no secret. The company domain defaults to your email’s domain for work addresses: the finishing run completes without --domain, while a personal-provider email (gmail, outlook, yahoo, …) still requires it; an explicit --domain always wins. A wrong --code answers the server’s INVALID_CODE envelope (exit 2); the attempt cap answers SIGNUP_ATTEMPTS_EXCEEDED, after which a fresh --email run restarts the flow. An interruption at ANY later point is equally recoverable by re-running with the same --email: a signup whose workspace never became usable is re-adopted after the new code is verified, and EMAIL_ALREADY_REGISTERED (409) answers only for a fully set-up account. Without --json: A terminal prints the browser hand-off (or the emailed-code prompt flow with —headless), then one confirmation line naming the new workspace and profile. Example output:

{
  "signedUp": true,
  "edition": "customer",
  "profile": "acme",
  "workspace": {
    "organizationId": "org_2abcDEFghij345",
    "name": "Acme",
    "plan": "Agents"
  },
  "actingAs": null,
  "baseUrl": "https://app.octolens.com",
  "pinnedBaseUrl": "https://app.octolens.com"
}

Headless step 1 (--headless --email without --code) answers the pending-signup coordinates instead and exits 0 — the emailed code cannot be read by this process.

Field	Type	Description
`signedUp`	boolean	Always `false` for the step-1 document.
`signupId`	string	Pending signup id — quote it back via `--signup-id` to finish.
`email`	string	Normalized email the code was sent to.
`expiresInSeconds`	integer	How long the emailed code stays valid.
`derivedDomain`	string \| null	The company domain the finishing run defaults to when `--domain` is omitted — your email’s domain for work addresses (`you@corp.com` → `corp.com`); `null` for personal providers (gmail, outlook, yahoo, …), which still require `--domain`. An explicit `--domain` always wins.
`next`	string	The exact finishing command, with `--signup-id` filled in — it only includes `--domain` when the domain could not be derived from the email.

Example output:

{
  "signedUp": false,
  "signupId": "4f2a9c81d6e05b37a1428f6f9c03d5aa",
  "email": "you@corp.com",
  "expiresInSeconds": 600,
  "derivedDomain": "corp.com",
  "next": "octolens signup --headless --signup-id 4f2a9c81d6e05b37a1428f6f9c03d5aa --code <code from the email>"
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE · 8 CANCELLED. The full map is on Exit codes.

`octolens switch`

Switch the active workspace profile Arguments

Argument	Type	Required	Description
`PROFILE`	`string`	optional	Profile name (or 1-based number) to switch to

Examples

octolens switch acme
octolens switch --json

Returns With --json, stdout carries one JSON document with these fields.

Field	Type	Description
`active`	string	The now-active profile name.
`changed`	boolean	`false` when the requested profile was already active (idempotent no-op).

Without --json: A terminal prints one confirmation line (interactive runs list the profiles and prompt first). Example output:

{
  "active": "globex",
  "changed": true
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE · 8 CANCELLED. The full map is on Exit codes.

`octolens whoami`

Show the active login: who you are, workspace, plan, and scope Examples

octolens whoami
octolens whoami --json

Returns With --json, stdout carries one JSON document with these fields. Backed by the v2 API operation GET /api/v2/auth.

Field	Type	Description
`edition`	enum: `internal`, `customer`	The CLI build edition (same value `version` reports).
`profile`	string \| null	The stored profile supplying the credential — `null` when auth comes from the environment.
`workspace`	object \| null	The authenticated workspace (`{organizationId, name, plan}`) — same shape `login` emits.
`workspace.organizationId`	string	Organization id.
`workspace.name`	string	Workspace name.
`workspace.plan`	string \| null	Current plan. `null` when none.
`actingAs`	object \| null	Present when acting on another workspace (`{orgId, workspace?}`). `null` otherwise.
`transport`	enum: `direct`, `rest`	The transport this run selected.
`authSource`	string	Where the selected transport’s credential came from (`profile`, `env`, …).
`scope`	string[] \| null	The credential’s LIVE effective scopes (`read`/`write`/`admin`) from auth introspection — the preflight an agent checks before mutating. `null` only when scopes are genuinely unknowable.
`baseUrl`	string	The effective app base URL for this configuration.
`ignoredEnv`	string[]	Env identity vars that are set but IGNORED for the selected transport (e.g. `OCTOLENS_ORG_ID` on REST, where the API key selects the workspace). Empty when nothing is ignored.

Without --json: A terminal renders the identity a human cares about (OCT-1545): workspace name + company domain, the acting user’s email (omitted when unavailable), a one-line company headline, the plan label (Agents renders as Sandbox) and scope. Org id / edition / transport / auth source stay JSON-only, and the base URL prints ONLY when it is non-default.

Example output

{
  "edition": "customer",
  "profile": "acme",
  "workspace": {
    "organizationId": "org_2abcDEFghij345",
    "name": "Acme",
    "plan": "Pro_v3"
  },
  "actingAs": null,
  "transport": "rest",
  "authSource": "profile",
  "scope": [
    "read",
    "write"
  ],
  "baseUrl": "https://app.octolens.com",
  "ignoredEnv": []
}

Exit codes — 0 OK · 1 UNEXPECTED · 2 USAGE. The full map is on Exit codes.

Get started

Contract

Commands

Concepts

Guides

Scripting & agents

`octolens logout`

`octolens switch`

`octolens whoami`

​octolens login

​octolens logout

​octolens signup

​octolens switch

​octolens whoami

`octolens login`

`octolens logout`

`octolens signup`

`octolens switch`

`octolens whoami`