# CLI Reference

The Lightsage CLI manages visibility data, prompts, content, evals, and reusable eval resources through the public API. This reference matches CLI `0.6.7`.

## Install

```bash
brew install lightsagehq/tools/lightsage
lightsage version
```

Upgrade an existing installation before using this reference:

```bash
brew update
brew upgrade lightsagehq/tools/lightsage
```

## Authenticate

Create an API key under **Settings > API Keys**, then store it in your operating system keychain:

```bash
lightsage auth login
```

For CI and agent sessions, set the key as an environment variable:

```bash
export LIGHTSAGE_API_KEY="ls_cli_your_api_key"
```

Check the credential source and validate the key:

```bash
lightsage auth whoami --no-interactive
lightsage status auth-status-get --no-interactive
```

> [!WARNING]
>
> API keys are shown once. Store them in a secret manager and never commit them.

## Command groups

- **[Visibility](/content/docs/cli-reference/visibility.md)**: Measure visibility and citations.
- **[Opportunities](/content/docs/cli-reference/opportunities.md)**: Review ranked visibility opportunities.
- **[Tasks](/content/docs/cli-reference/tasks.md)**: Manage the action queue.
- **[Prompts](/content/docs/cli-reference/prompts.md)**: Manage tracked prompts.
- **[Prompt topics](/content/docs/cli-reference/prompt-topics.md)**: Organize prompts into topics.
- **[Prompt runs](/content/docs/cli-reference/prompt-runs.md)**: Inspect stored prompt runs.
- **[Content](/content/docs/cli-reference/content.md)**: Draft and finalize articles.
- **[Site audits](/content/docs/cli-reference/site-audit.md)**: Review page-level audit findings.
- **[Evals](/content/docs/cli-reference/evals.md)**: Define evals and configurations.
- **[Eval runs](/content/docs/cli-reference/eval-runs.md)**: Start and inspect eval jobs.
- **[Eval results](/content/docs/cli-reference/eval-results.md)**: Review completed outcomes.
- **[Eval resources](/content/docs/cli-reference/agents.md)**: Discover agents, repositories, environments, MCP servers, CLIs, and skills.

## Complete command coverage

The CLI exposes 52 API-backed commands:

| Area | Commands |
| - | - |
| Agents | `agents list` |
| CLIs | `clis list` |
| Content | `content drafts create`, `content finalize`, `content retrieve` |
| Environments | `environments list` |
| Eval results | `eval-results list`, `eval-results retrieve` |
| Eval runs | `eval-runs create`, `eval-runs list`, `eval-runs retrieve` |
| Evals | `evals create`, `evals delete`, `evals list`, `evals retrieve`, `evals update` |
| Eval configurations | `evals configurations create`, `delete`, `list`, `retrieve`, `update` |
| MCP servers | `mcp-servers list` |
| Opportunities | `opportunities list`, `opportunities retrieve` |
| Prompts | `prompts create`, `delete`, `list`, `retrieve`, `update` |
| Prompt runs | `prompts runs list`, `prompts runs retrieve` |
| Prompt topics | `prompts topics create`, `delete`, `list`, `update` |
| Repositories | `repositories create`, `delete`, `list`, `retrieve`, `update` |
| Site audits | `site-audits list`, `site-audits retrieve` |
| Skills | `skills list` |
| Status | `status auth-status-get`, `status get` |
| Tasks | `tasks create`, `tasks list`, `tasks retrieve`, `tasks update` |
| Visibility | `visibility citations-list`, `current-retrieve`, `overview-retrieve`, `prompts-retrieve` |

The `api-performance` namespace is not available in CLI `0.6.7`. Use `evals`, `eval-runs`, `eval-results`, and the eval-resource command groups instead.

## Global flags

| Flag | Description |
| - | - |
| `--lightsage-api-key-auth` | Use an API key for this command. |
| `-o`, `--output-format` | Select `pretty`, `json`, `yaml`, `table`, or `toon`. |
| `-q`, `--jq` | Filter JSON-compatible output with a jq expression. |
| `--no-interactive` | Disable prompts, forms, and explorer fallback behavior. |
| `--agent-mode` | Use structured errors and agent-friendly output defaults. |
| `--dry-run` | Print the request without sending it. |
| `--include-headers` | Include HTTP response headers. |
| `-H`, `--header` | Add a request header. Repeat the flag for multiple headers. |
| `--server`, `--server-url` | Select or override the API server. |
| `--timeout` | Set the HTTP timeout, such as `30s` or `5m`. |
| `--debug` | Print request and response diagnostics to stderr. |
| `--usage` | Print the complete CLI schema in KDL format. |

Use JSON output for scripts:

```bash
lightsage eval-runs list --output-format json --no-interactive
```

Use `--help` on any command to inspect its current flags:

```bash
lightsage eval-runs create --help
```