> ## Documentation Index
> Fetch the complete documentation index at: https://lightsage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompts

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

Prompt commands create batches and manage individual Visibility prompts.

Use [Topics](https://lightsage.com/docs/cli-reference/prompt-topics.md) to manage prompt topics, [Prompt runs](https://lightsage.com/docs/cli-reference/prompt-runs.md) to inspect stored runs, and [Opportunities](https://lightsage.com/docs/cli-reference/opportunities.md) 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

```bash theme={null}
lightsage prompts list --output-format table
```

Filter by topic or lifecycle status:

```bash theme={null}
lightsage prompts list \
  --topic-id topic_123 \
  --status active
```

Include archived prompts:

```bash theme={null}
lightsage prompts list --include-archived
```

## Create prompts

Create multiple Visibility prompts in one request:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
lightsage prompts retrieve --prompt-id prompt_123
```

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

```bash theme={null}
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:

```bash theme={null}
lightsage prompts delete --prompt-id prompt_123
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.