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

# Prompts

> Manage prompt templates and versions with the AX CLI

<Note>
  The `ax prompts` commands are currently in **BETA**. The API may change without notice. A one-time warning is emitted on first use.
</Note>

The `ax prompts` commands let you create and manage prompt templates and their versions on the Arize platform.

## `ax prompts list`

List prompts in a space.

```bash theme={null}
ax prompts list [--space <id>] [--name <filter>] [--limit <n>] [--cursor <cursor>]
```

| Option     | Description                                       |
| ---------- | ------------------------------------------------- |
| `--space`  | Space name or ID to filter prompts                |
| `--name`   | Case-insensitive substring filter on prompt name  |
| `--limit`  | Maximum number of results to return (default: 15) |
| `--cursor` | Pagination cursor for the next page               |

**Examples:**

```bash theme={null}
ax prompts list --space sp_abc123
ax prompts list --space sp_abc123 --output prompts.json
```

## `ax prompts create`

Create a prompt with an initial version. Pass messages as a path to a JSON file or inline JSON.

```bash theme={null}
ax prompts create \
  --name <name> \
  --space <id> \
  --provider <provider> \
  --input-variable-format <format> \
  --messages <json-or-path>
```

| Option                    | Description                                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| `--name`                  | Prompt name (must be unique within the space)                                               |
| `--space`                 | Space name or ID to create the prompt in                                                    |
| `--provider`              | LLM provider: `open_ai`, `azure_open_ai`, `aws_bedrock`, `vertex_ai`, `anthropic`, `custom` |
| `--input-variable-format` | Variable interpolation format: `f_string`, `mustache`, `none`                               |
| `--messages`              | Path to a JSON file, or inline JSON array of message objects                                |
| `--commit-message`        | Commit message for the initial version (default: `"Initial version"`)                       |
| `--description`           | Optional prompt description                                                                 |
| `--model`                 | Default model name for this version                                                         |

Messages must be a non-empty JSON array. Each message object needs a `role` and optionally `content`, `tool_call_id`, or `tool_calls`:

```json theme={null}
[
  {"role": "system", "content": "You are a helpful assistant for {company}."},
  {"role": "user", "content": "Answer the question: {question}"}
]
```

**Examples:**

```bash theme={null}
# From a JSON file
ax prompts create \
  --name "support-agent" \
  --space sp_abc123 \
  --provider open_ai \
  --input-variable-format f_string \
  --messages ./messages.json \
  --model gpt-4o

# Inline JSON
ax prompts create \
  --name "summarizer" \
  --space sp_abc123 \
  --provider open_ai \
  --input-variable-format f_string \
  --messages '[{"role":"user","content":"Summarize: {text}"}]' \
  --model gpt-4o-mini
```

## `ax prompts get`

Get a prompt by name or ID. Optionally resolve a specific version via `--version-id` or `--label`. If neither is supplied, the latest version is returned.

```bash theme={null}
ax prompts get <name-or-id> [--space <id>] [--version-id <id>] [--label <label>]
```

| Option         | Description                                                      |
| -------------- | ---------------------------------------------------------------- |
| `--space`      | Space name or ID (required when using prompt name instead of ID) |
| `--version-id` | Specific version ID to retrieve                                  |
| `--label`      | Label name to resolve to a version (e.g. `production`)           |

**Examples:**

```bash theme={null}
ax prompts get pr_abc123
ax prompts get "support-agent" --space sp_abc123
ax prompts get pr_abc123 --version-id prv_xyz789
ax prompts get pr_abc123 --label production
```

## `ax prompts update`

Update a prompt's description.

```bash theme={null}
ax prompts update <name-or-id> [--space <id>] --description <desc>
```

| Option          | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| `--space`       | Space name or ID (required when using prompt name instead of ID) |
| `--description` | Updated description for the prompt                               |

**Example:**

```bash theme={null}
ax prompts update pr_abc123 --description "Updated description for customer support prompt"
```

## `ax prompts delete`

Delete a prompt and all its versions. This operation is irreversible.

```bash theme={null}
ax prompts delete <name-or-id> [--space <id>] [--force]
```

| Option    | Description                                                      |
| --------- | ---------------------------------------------------------------- |
| `--space` | Space name or ID (required when using prompt name instead of ID) |
| `--force` | Skip the confirmation prompt                                     |

**Examples:**

```bash theme={null}
ax prompts delete pr_abc123
ax prompts delete pr_abc123 --force
ax prompts delete "support-agent" --space sp_abc123 --force
```

## `ax prompts list-versions`

List versions for a prompt.

```bash theme={null}
ax prompts list-versions <name-or-id> [--space <id>] [--limit <n>] [--cursor <cursor>]
```

| Option     | Description                                                      |
| ---------- | ---------------------------------------------------------------- |
| `--space`  | Space name or ID (required when using prompt name instead of ID) |
| `--limit`  | Maximum number of versions to return (default: 15)               |
| `--cursor` | Pagination cursor for the next page                              |

**Example:**

```bash theme={null}
ax prompts list-versions pr_abc123
```

## `ax prompts create-version`

Create a new version for an existing prompt. Pass messages as a path to a JSON file or inline JSON.

```bash theme={null}
ax prompts create-version <name-or-id> \
  --provider <provider> \
  --input-variable-format <format> \
  --messages <json-or-path>
```

| Option                    | Description                                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| `--space`                 | Space name or ID (required when using prompt name instead of ID)                            |
| `--provider`              | LLM provider: `open_ai`, `azure_open_ai`, `aws_bedrock`, `vertex_ai`, `anthropic`, `custom` |
| `--input-variable-format` | Variable interpolation format: `f_string`, `mustache`, `none`                               |
| `--messages`              | Path to a JSON file, or inline JSON array of message objects                                |
| `--commit-message`        | Commit message describing this version (default: `"New version"`)                           |
| `--model`                 | Default model name for this version                                                         |

**Example:**

```bash theme={null}
ax prompts create-version pr_abc123 \
  --provider open_ai \
  --input-variable-format f_string \
  --messages ./updated_messages.json \
  --commit-message "Improved tone for edge cases" \
  --model gpt-4o
```

## `ax prompts get-version-by-label`

Resolve a label to the prompt version it points to.

```bash theme={null}
ax prompts get-version-by-label <name-or-id> --label <label> [--space <id>]
```

| Option    | Description                                                      |
| --------- | ---------------------------------------------------------------- |
| `--label` | Label name to resolve (e.g. `production`, `staging`)             |
| `--space` | Space name or ID (required when using prompt name instead of ID) |

**Example:**

```bash theme={null}
ax prompts get-version-by-label pr_abc123 --label production
```

## `ax prompts set-version-labels`

Set labels on a prompt version. Replaces all existing labels on the version with the provided list.

```bash theme={null}
ax prompts set-version-labels <version-id> --label <label> [--label <label> ...]
```

**Examples:**

```bash theme={null}
ax prompts set-version-labels prv_xyz789 --label production
ax prompts set-version-labels prv_xyz789 --label production --label staging
```

## `ax prompts remove-version-label`

Remove a label from a prompt version. This does not delete the version itself.

```bash theme={null}
ax prompts remove-version-label <version-id> --label <label>
```

**Example:**

```bash theme={null}
ax prompts remove-version-label prv_xyz789 --label staging
```