> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithlocus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Locus CLI

> Install the official Locus CLI, authenticate, and call Locus Pro from a terminal or agent runtime.

The Locus CLI gives people, scripts, and terminal-native agents structured
access to Locus Pro. The public release bundle includes the `locus` binary, its
version-matched command reference, optional Okibi Identity support, and an agent
skill.

## Install

Install the current official release on macOS or Linux:

```bash theme={null}
curl -fsSL https://paywithlocus.com/install/locus | sh
export PATH="${LOCUS_BIN_DIR:-${HOME}/.local/bin}:${PATH}"
```

The installer detects your platform, verifies the downloaded archive's SHA-256
checksum, and installs both the CLI and its matching agent skill. The `export`
line makes the binary available in the current shell, including when you set a
custom `LOCUS_BIN_DIR`; add that directory to your shell profile to keep it
available in new shells.

Verify the installation:

```bash theme={null}
locus --version
locus doctor
```

The current repo-backed release targets
`https://api.paywithlocus.com/api` by default. Use an explicit profile only
when you intentionally need an isolated stage or local environment. Stage and
production credentials, workspaces, and balances are separate.

Re-run the same install command to upgrade to the current official release.

## Authenticate

Start the authentication flow advertised by the Locus API:

```bash theme={null}
locus auth login
locus auth status
```

When Okibi Identity is available for the selected Locus environment, the CLI
uses its bundled, release-matched identity helper. Otherwise, use Locus Pro's
native authentication explicitly:

```bash theme={null}
locus auth native
```

For a non-interactive service, provide an existing scoped credential through
its secret manager or environment:

```bash theme={null}
export LOCUS_SECRET_KEY="$LOCUS_AGENT_CONNECTION"
```

Native authentication is independent of Okibi Identity. A valid
`LOCUS_SECRET_KEY` continues to work when Identity is disabled or a release is
not yet Identity-eligible.

Prefer an Agent Connection credential (`lcac_…`) for an unattended agent. It
can restrict endpoints, account access, expiry, and spend. Do not place a broad
tenant secret key in an agent or prompt. See [Connect an agent](/locus-pro/connect-agents)
for the credential model.

If login or connectivity fails, inspect the active mode without exposing the
stored credential:

```bash theme={null}
locus auth doctor
locus doctor
```

## Discover commands

Start with built-in help. Each command and subcommand has its own reference:

```bash theme={null}
locus --help
locus catalog --help
locus catalog search-enabled-executable-tools --help
```

Use `which` when you know the job but not the command:

```bash theme={null}
locus which "search the catalog"
```

Common command groups include:

| Command             | Use                                           |
| ------------------- | --------------------------------------------- |
| `locus catalog`     | Search and manage available tools             |
| `locus credentials` | Create and verify scoped credentials          |
| `locus end-users`   | Manage end-user billing identities            |
| `locus ledger`      | Read usage and credit activity                |
| `locus mcp`         | Manage MCP resources                          |
| `locus tenants`     | Read and manage enterprise workspace settings |
| `locus top-ups`     | Read and create funding operations            |
| `locus webhooks`    | Manage event delivery                         |
| `locus workflow`    | Run compound multi-step operations            |

## Use it from an agent

Add `--agent` to apply the non-interactive defaults agents need: JSON output,
compact fields, no color, no prompts, and confirmed execution.

```bash theme={null}
locus catalog search-enabled-executable-tools \
  --query "company enrichment" \
  --agent
```

Use `--dry-run` on a write to inspect the request without sending it:

```bash theme={null}
locus tenants update-tenant-profile --help
locus tenants update-tenant-profile \
  --name "Research workspace" \
  --dry-run \
  --agent
```

The installer places the version-matched Locus skill in detected agent skill
directories. An agent can use that reference to choose commands and flags
without copying generated instructions into a prompt.

## Output and automation

Every command supports predictable output controls:

| Flag                      | Behavior                                       |
| ------------------------- | ---------------------------------------------- |
| `--json`                  | Return structured JSON                         |
| `--compact`               | Keep only common identifying and status fields |
| `--select id,name,status` | Return only selected fields                    |
| `--csv`                   | Return array or table results as CSV           |
| `--plain`                 | Return tab-separated text                      |
| `--quiet`                 | Return one bare value per line                 |
| `--no-input`              | Fail instead of prompting                      |
| `--dry-run`               | Print a write request without sending it       |

Use a unique idempotency key when the selected command exposes one, and reuse
that key when retrying the same logical write. Do not treat a client timeout as
proof that a paid or state-changing request failed.

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/locus-pro/quickstart">
    Make your first metered API call.
  </Card>

  <Card title="Connect an agent" icon="robot" href="/locus-pro/connect-agents">
    Issue a least-privilege credential for an unattended runtime.
  </Card>
</CardGroup>