prompts.md

Prompts

Create, list, retrieve, update, and delete Visibility prompts from the Lightsage CLI.

Prompt commands create batches and manage individual Visibility prompts.

Use Topics to manage prompt topics, Prompt runs to inspect stored runs, and Opportunities to review ranked improvements.

Commands

Command	Description
`lightsage prompts list`	List Visibility prompts.
`lightsage prompts create`	Create one or more Visibility prompts.
`lightsage prompts retrieve --prompt-id <prompt_id>`	Retrieve one prompt.
`lightsage prompts update --prompt-id <prompt_id>`	Update one prompt.
`lightsage prompts delete --prompt-id <prompt_id>`	Delete one prompt.

List prompts

lightsage prompts list --output-format table

Filter by topic or lifecycle status:

lightsage prompts list \
  --topic-id topic_123 \
  --status active

Include archived prompts:

lightsage prompts list --include-archived

Create prompts

Create multiple Visibility prompts in one request:

lightsage prompts create \
  --prompts '[{"text":"What is the best API for crawling websites?","topic_id":"topic_123","platform_ids":["chatgpt"],"run_settings":{"search_grounding":"enabled","web_search_instruction":"append"}},{"text":"Which API should I use to extract structured data from a webpage?","topic_id":"topic_123","platform_ids":["chatgpt"]}]'

The --prompts value is a JSON array. Each prompt object requires text and topic_id. Include platform_ids to choose tracked AI platforms.

Use run_settings to control coding-agent web access:

Field	Values	Behavior
`search_grounding`	`disabled`, `enabled`, `default`	Block web access, require web retrieval, or let the agent choose.
`web_search_instruction`	`omit`, `append`, `both`	Keep the prompt unchanged, append "Use web search.", or run both variants.

These settings do not affect answer engines. A grounding setting supplied when starting an eval run overrides the prompt setting for that run.

Example response:

{
  "created": [
    {
      "id": "prompt_123",
      "topic_id": "topic_123",
      "text": "What is the best API for crawling websites?",
      "status": "active",
      "run_settings": {
        "search_grounding": "enabled",
        "web_search_instruction": "append"
      }
    }
  ],
  "count": 1,
  "errors": []
}

Retrieve, update, and delete prompts

Retrieve one prompt:

lightsage prompts retrieve --prompt-id prompt_123

Update prompt text, topic, platforms, lifecycle status, or coding-agent run settings:

lightsage prompts update --prompt-id prompt_123 \
  --text "What is the best web crawling API for Node.js?" \
  --status active \
  --run-settings '{"search_grounding":"disabled","web_search_instruction":"omit"}'

Delete one prompt:

lightsage prompts delete --prompt-id prompt_123