CLI Reference - Lightsage

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

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