CLI Reference

Install, authenticate, and navigate the Sapient CLI.

The Sapient CLI lets you create Visibility prompts, inspect prompt opportunities, and manage API Performance resources from your terminal. It uses Sapient’s public API contract.

The CLI uses API key authentication. It does not require browser login.

Install

Install Sapient with Homebrew:

brew install usesapient/tools/sapient

Check that the CLI is available:

sapient version

Authenticate

Create an API key in the Sapient dashboard.

1. Open Settings > API Keys.
2. Click Create API key.
3. Copy the key when it is shown.

Store the key with the CLI:

sapient auth login

The CLI stores secret credentials in your operating system keychain when available. This is the recommended setup for local development because the key persists across terminal and agent sessions.

You can also save the key non-interactively:

sapient configure --sapient-api-key-auth "sapient_your_api_key"

Check which credential source the CLI is using:

sapient auth whoami --no-interactive

Then verify that the key can authenticate API requests:

sapient status auth-status-get --no-interactive

For CI, containers, or agent sessions where the keychain is not available, set the key as an environment variable:

export CLI_SAPIENT_API_KEY_AUTH="sapient_your_api_key"

Add that export to your shell profile or secret manager if it should persist across sessions. Environment variables take precedence over the keychain.

You can also pass the key for one command. This does not save the key:

sapient --sapient-api-key-auth "sapient_your_api_key" status auth-status-get

API keys are shown once. Store the key in your secret manager or shell profile. Do not commit it to your repository.

Command groups

Prompts

Create, list, update, and delete Visibility prompts.

Topics

Create, update, and delete prompt topics.

Actions

List prompt actionables, cited pages, and opportunities.

Eval runs

Start durable eval runs and poll their progress.

API Performance runs

List recent eval runs and retrieve a full run result.

Targets

Discover text models and coding-agent model choices.

Configuration

Read and update models, targets, evals, env vars, and base URL.

Sources

List tracked API Performance sources and their scheduled targets.

Skills

List reusable skill context for API Performance evals.

Eval definitions

Inspect and tune prompts, expected behavior, and run context.

Custom evals

Create higher-level task evals for coding agents.

Starter projects

Manage repositories cloned before agent evals run.

Actions

List, update, refresh, and verify API Performance actions.

Global flags

Flag	Environment variable	Description
--sapient-api-key-auth	CLI_SAPIENT_API_KEY_AUTH	Authenticates public API requests. Flags apply only to the current command.
-o, --output-format		Changes output format. Common values are pretty, json, yaml, table, and toon.
-q, --jq		Filters JSON-compatible output with a jq expression.
--no-interactive		Disables prompts, forms, and explorer fallback behavior.

Status commands

Use status commands to check API availability and authentication.

Command	Description
sapient status get	Check public API health.
sapient status auth-status-get	Check whether your API key is valid.
sapient auth whoami	Show the current auth configuration and source.
sapient auth logout	Clear stored credentials from the keychain and config file.

Example health response:

{
  "status": "ok"
}

Example auth response:

{
  "authenticated": true,
  "org_id": "org_123",
  "api_key_id": "key_123",
  "scopes": ["read", "write", "jobs:read", "jobs:run", "jobs:cancel"]
}

Reference scope

The CLI Reference covers the current public API scope.

Area	Commands
Prompts	sapient prompts list, create, retrieve, update, delete; config retrieve
Prompt topics	sapient prompts topics create, update, delete
Prompt actions	sapient prompts actions list
Eval runs	sapient eval-runs create, retrieve
API Performance runs	sapient api-performance runs list, retrieve; sapient api-performance diagnose
API Performance targets	sapient api-performance targets list
API Performance config	sapient api-performance config retrieve, update
API Performance sources	sapient api-performance sources list
API Performance skills	sapient api-performance skills list
API Performance eval definitions	sapient api-performance evals list, retrieve, update
API Performance custom evals	sapient api-performance custom-evals list, create, retrieve, update, delete; custom-evals history list
API Performance starter projects	sapient api-performance starter-projects list, create, retrieve, update, delete
API Performance actions	sapient api-performance actions list, refresh, retrieve, update, verify

The CLI no longer exposes context, workflows, jobs, leaderboard companies, lower-level /v1/api/* commands, or public brand selectors.

Output

Use --output-format json when you need stable output for scripts:

sapient api-performance runs list --output-format json

The default pretty output is optimized for humans and can change between CLI releases.

Troubleshooting

Symptom	What to check
401 Unauthorized	Run sapient auth whoami. If the keychain has a stale key, run sapient auth logout and then sapient auth login. For CI or agent shells, confirm CLI_SAPIENT_API_KEY_AUTH is set.
403 Forbidden	Confirm the API key has access to the command area you are using.
500 Internal Server Error	Retry once, then contact Sapient support with the command and approximate time.
Unknown command or stale flags	Upgrade the CLI with brew upgrade sapient and rerun the command with --help.