## Commands

Prompt commands create batches and manage individual Visibility prompts. Use [Topics](/content/docs/cli-reference/prompt-topics/index.html) to manage prompt topics, [Prompt runs](/content/docs/cli-reference/prompt-runs/index.html) to inspect stored runs, and [Opportunities](/content/docs/cli-reference/opportunities/index.html) to review ranked improvements.

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