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

# CLI Reference

> Install, authenticate, and navigate the Lightsage CLI.

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.

<Note>
  The CLI uses API key authentication. It does not require browser login.
</Note>

## Install

Install Lightsage with Homebrew:

```bash theme={null}
brew install lightsagehq/tools/lightsage
```

Check that the CLI is available:

```bash theme={null}
lightsage version
```

## Authenticate

Create an API key in the Lightsage 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:

```bash theme={null}
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:

```bash theme={null}
lightsage configure --lightsage-api-key-auth "ls_cli_your_api_key"
```

Check which credential source the CLI is using:

```bash theme={null}
lightsage auth whoami --no-interactive
```

Then verify that the key can authenticate API requests:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
lightsage --lightsage-api-key-auth "ls_cli_your_api_key" status auth-status-get
```

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

## Command groups

<CardGroup cols={2}>
  <Card title="Prompts" icon="message" href="/docs/cli-reference/prompts">
    Create, list, update, and delete Visibility prompts.
  </Card>

  <Card title="Topics" icon="list-tree" href="/docs/cli-reference/prompt-topics">
    Create, update, and delete prompt topics.
  </Card>

  <Card title="Actions" icon="sparkles" href="/docs/cli-reference/prompt-actions">
    List prompt actionables, cited pages, and opportunities.
  </Card>

  <Card title="Eval runs" icon="play" href="/docs/cli-reference/eval-runs">
    Start durable eval runs and poll their progress.
  </Card>

  <Card title="API Performance runs" icon="list" href="/docs/cli-reference/api-performance-runs">
    List recent eval runs and retrieve a full run result.
  </Card>

  <Card title="Targets" icon="bullseye" href="/docs/cli-reference/api-performance-targets">
    Discover text models and coding-agent model choices.
  </Card>

  <Card title="Configuration" icon="sliders" href="/docs/cli-reference/api-performance-config">
    Read and update models, targets, evals, env vars, and base URL.
  </Card>

  <Card title="Sources" icon="plug" href="/docs/cli-reference/api-performance-sources">
    List tracked API Performance sources and their scheduled targets.
  </Card>

  <Card title="Skills" icon="wrench" href="/docs/cli-reference/api-performance-skills">
    List reusable skill context for API Performance evals.
  </Card>

  <Card title="Eval definitions" icon="clipboard-list" href="/docs/cli-reference/api-performance-evals">
    Inspect and tune prompts, expected behavior, and run context.
  </Card>

  <Card title="Custom evals" icon="list-checks" href="/docs/cli-reference/api-performance-custom-evals">
    Create higher-level task evals for coding agents.
  </Card>

  <Card title="Starter projects" icon="folder-tree" href="/docs/cli-reference/api-performance-starter-projects">
    Manage repositories cloned before agent evals run.
  </Card>

  <Card title="Actions" icon="sparkles" href="/docs/cli-reference/api-performance-actions">
    List, update, refresh, and verify API Performance actions.
  </Card>
</CardGroup>

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

```json theme={null}
{
  "status": "ok"
}
```

Example auth response:

```json theme={null}
{
  "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](/docs/api-reference/introduction).

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

```bash theme={null}
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`.                                                                                                              |