CLI Reference - Lightsage

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

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

Install

Install Lightsage with Homebrew:

brew install lightsagehq/tools/lightsage

Check that the CLI is available:

lightsage version

Authenticate

Create an API key in the Lightsage dashboard.

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

Store the key with the CLI:

lightsage 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:

lightsage configure --lightsage-api-key-auth "ls_cli_your_api_key"

Check which credential source the CLI is using:

lightsage auth whoami --no-interactive

Then verify that the key can authenticate API requests:

lightsage 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_LIGHTSAGE_API_KEY_AUTH="ls_cli_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:

lightsage --lightsage-api-key-auth "ls_cli_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
`--lightsage-api-key-auth`	`CLI_LIGHTSAGE_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
`lightsage status get`	Check public API health.
`lightsage status auth-status-get`	Check whether your API key is valid.
`lightsage auth whoami`	Show the current auth configuration and source.
`lightsage 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. For HTTP endpoints, request schemas, and the interactive API playground, see the API Reference.

Area	Commands
Prompts	`lightsage prompts list`, `create`, `retrieve`, `update`, `delete`; `config retrieve`
Prompt topics	`lightsage prompts topics create`, `update`, `delete`
Prompt actions	`lightsage prompts actions list`
Eval runs	`lightsage eval-runs create`, `retrieve`
API Performance runs	`lightsage api-performance runs list`, `retrieve`; `lightsage api-performance diagnose`
API Performance targets	`lightsage api-performance targets list`
API Performance config	`lightsage api-performance config retrieve`, `update`
API Performance sources	`lightsage api-performance sources list`
API Performance skills	`lightsage api-performance skills list`
API Performance eval definitions	`lightsage api-performance evals list`, `retrieve`, `update`
API Performance custom evals	`lightsage api-performance custom-evals list`, `create`, `retrieve`, `update`, `delete`; `custom-evals history list`
API Performance starter projects	`lightsage api-performance starter-projects list`, `create`, `retrieve`, `update`, `delete`
API Performance actions	`lightsage 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:

lightsage 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 `lightsage auth whoami`. If the keychain has a stale key, run `lightsage auth logout` and then `lightsage auth login`. For CI or agent shells, confirm `CLI_LIGHTSAGE_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 Lightsage support with the command and approximate time.
Unknown command or stale flags	Upgrade the CLI with `brew upgrade lightsage` and rerun the command with `--help`.

​Install

​Authenticate

​Command groups

Prompts

Topics

Actions

Eval runs

API Performance runs

Targets

Configuration

Sources

Skills

Eval definitions

Custom evals

Starter projects

Actions

​Global flags

​Status commands

​Reference scope

​Output

​Troubleshooting

Install

Authenticate

Command groups

Global flags

Status commands

Reference scope

Output

Troubleshooting