> ## 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 manages visibility data, prompts, content, evals, and reusable eval resources through the public API. This reference matches CLI `0.6.7`.

## Install

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

Upgrade an existing installation before using this reference:

```bash theme={null}
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 theme={null}
lightsage auth login
```

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

```bash theme={null}
export LIGHTSAGE_API_KEY="ls_cli_your_api_key"
```

Check the credential source and validate the key:

```bash theme={null}
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](https://lightsage.com/docs/cli-reference/visibility.md)**
>
> Measure visibility and citations.

> **[Opportunities](https://lightsage.com/docs/cli-reference/opportunities.md)**
>
> Review ranked visibility opportunities.

> **[Tasks](https://lightsage.com/docs/cli-reference/tasks.md)**
>
> Manage the action queue.

> **[Prompts](https://lightsage.com/docs/cli-reference/prompts.md)**
>
> Manage tracked prompts.

> **[Prompt topics](https://lightsage.com/docs/cli-reference/prompt-topics.md)**
>
> Organize prompts into topics.

> **[Prompt runs](https://lightsage.com/docs/cli-reference/prompt-runs.md)**
>
> Inspect stored prompt runs.

> **[Content](https://lightsage.com/docs/cli-reference/content.md)**
>
> Draft and finalize articles.

> **[Site audits](https://lightsage.com/docs/cli-reference/site-audit.md)**
>
> Review page-level audit findings.

> **[Evals](https://lightsage.com/docs/cli-reference/evals.md)**
>
> Define evals and configurations.

> **[Eval runs](https://lightsage.com/docs/cli-reference/eval-runs.md)**
>
> Start and inspect eval jobs.

> **[Eval results](https://lightsage.com/docs/cli-reference/eval-results.md)**
>
> Review completed outcomes.

> **[Eval resources](https://lightsage.com/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 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 theme={null}
lightsage eval-runs list --output-format json --no-interactive
```

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

```bash theme={null}
lightsage eval-runs create --help
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.