Skip to main content
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:
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:
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:
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:
For a non-interactive service, provide an existing scoped credential through its secret manager or environment:
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 for the credential model. If login or connectivity fails, inspect the active mode without exposing the stored credential:

​
Discover commands

Start with built-in help. Each command and subcommand has its own reference:
Use which when you know the job but not the command:
Common command groups include:

​
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.
Use --dry-run on a write to inspect the request without sending it:
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: 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

Quickstart

Make your first metered API call.

Connect an agent

Issue a least-privilege credential for an unattended runtime.