# Install and use the Locus CLI

Canonical skill: `https://paywithlocus.com/skill.md`

Use this guide only when the user explicitly requests the generated Locus CLI,
or when the canonical skill selects it for a runtime with shell access but no
native MCP client. The CLI and MCP are separate integrations; installing or
authenticating one does not configure the other.
Do not switch to MCP without the user's direction.

For the underlying identity, account-linking, and credential-bootstrap
contract, read the
[authentication reference](https://paywithlocus.com/agent/auth.md#generated-cli-path-okibi-identity).

## Install or update

Require `compatibility.cli.available: true`, then confirm that its configured
API publishes Okibi Identity before installing:

```bash
curl -fsS https://api.paywithlocus.com/.well-known/okibi-identity
```

Continue only when that request returns a valid Identity manifest. Use the
exact `compatibility.cli.install_url`; do not construct one from the API or
landing origin. Install the official signed release and put its bin directory
on `PATH`:

```bash
curl -fsSL '<compatibility.cli.install_url>' | sh
export PATH="${LOCUS_BIN_DIR:-${HOME}/.local/bin}:${PATH}"
locus --version
```

Rerun the same installer to update an installation it manages. Do not replace
an unrelated executable if the installer reports that the destination is
already occupied; inspect `command -v locus` and the resolved symlink first.

## Authenticate

Inspect state before starting another login:

```bash
locus auth status --json
```

When no usable session and native credential are present, start Okibi Identity
login:

```bash
locus auth login
```

The browser may request email verification and scope approval. A previously
linked Locus account can return directly to the localhost callback without
visiting a Locus page; that is expected. The login is ready only when
`locus auth status --json` reports all of the following:

- `mode` is `okibi_identity`;
- the identity and installation sessions are present; and
- `native_credential` is `true`.

An installation session by itself is not proof that ordinary CLI commands can
authenticate.

### Recover a native-mode bootstrap failure

If login completes but ends with this error:

```text
authorizing Locus credential bootstrap: configured API did not accept Okibi Identity for this request
```

the Identity helper may still be pinned to native mode. Preserve the new
Identity session, switch the helper back to Identity mode, and retry without
forcing another human login:

```bash
locus auth native --off
locus auth login
```

If the user explicitly requested a complete local reset, use this order so
`logout` cannot leave the durable native-mode choice behind:

```bash
locus auth logout
locus auth native --off
locus auth login --fresh
```

Do not change Cognito callbacks, weaken Locus authentication, or substitute a
different bearer token for this failure. The failed bootstrap request has not
reached the Locus API with Okibi authorization.

## Verify

Run both state inspection and a read-only command permitted by the installed
credential:

```bash
locus auth status --json
locus okibi read-okibi-cli-credential-bootstrap-status --json
```

The protected status command should report `credentialConfigured: true` and an
active connection without exposing the credential.

The current generated `doctor` command probes a management-only credential
endpoint. An execution-scoped `lcac_` credential can therefore be valid even
when `locus doctor` reports `invalid (HTTP 401)`. Do not delete or replace a
credential based on that diagnostic alone; confirm the auth state and a
read-only operation within the credential's scope.

## Find and run commands

Use the CLI's own index and help rather than guessing generated command names:

```bash
locus which "describe the capability you need"
locus <group> --help
locus <group> <command> --help
```

Prefer structured, non-interactive output for agent work:

```bash
locus <group> <command> --agent
```

`--agent` enables JSON, compact output, no color, no prompts, and confirmed
execution. Add `--dry-run` before mutations or paid calls when the command
supports it. Do not perform a paid call merely to test authentication.

The credential installed by Okibi bootstrap is a scoped native `lcac_`
credential. Its endpoint allowlist is authoritative: it is not a tenant
management key and does not grant access to every generated command. Never
print it, pass it as a positional argument, copy it into MCP configuration, or
store it in a project file.

After authentication, return to the
[canonical Locus Pro skill](https://paywithlocus.com/skill.md) when the request
also requires capability selection, funding, or readiness reporting.