index.md

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

brew install lightsagehq/tools/lightsage
lightsage version

Upgrade an existing installation before using this reference:

brew update
brew upgrade lightsagehq/tools/lightsage

Authenticate

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

lightsage auth login

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

export LIGHTSAGE_API_KEY="ls_cli_your_api_key"

Check the credential source and validate the key:

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: Measure visibility and citations.
Opportunities: Review ranked visibility opportunities.
Tasks: Manage the action queue.
Prompts: Manage tracked prompts.
Prompt topics: Organize prompts into topics.
Prompt runs: Inspect stored prompt runs.
Content: Draft and finalize articles.
Site audits: Review page-level audit findings.
Evals: Define evals and configurations.
Eval runs: Start and inspect eval jobs.
Eval results: Review completed outcomes.
Eval resources: 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:

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

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

lightsage eval-runs create --help