CLI Reference - Lightsage

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

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

​Install

​Authenticate

​Command groups

Visibility

Opportunities

Tasks

Prompts

Prompt topics

Prompt runs

Content

Site audits

Evals

Eval runs

Eval results

Eval resources

​Complete command coverage

​Global flags

Install

Authenticate

Command groups

Complete command coverage

Global flags