> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/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`, `-s`   | Space name or ID to filter prompts                             |
| `--name`, `-n`    | Case-insensitive substring filter on prompt name               |
| `--limit`, `-l`   | Maximum number of results to return (default: 15)              |
| `--cursor`, `-c`  | Pagination cursor for the next page                            |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path |
| `--verbose`, `-v` | Enable verbose logs                                            |

**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`, `-n`            | Prompt name (must be unique within the space) — required                                                     |
| `--space`, `-s`           | Space name or ID to create the prompt in — required                                                          |
| `--provider`              | LLM provider: `open_ai`, `azure_open_ai`, `aws_bedrock`, `vertex_ai`, `anthropic`, `custom` — required       |
| `--input-variable-format` | Variable interpolation format: `f_string`, `mustache`, `none` — required                                     |
| `--messages`              | Path to a JSON file, or inline JSON array of message objects — required                                      |
| `--commit-message`        | Commit message for the initial version (default: `"Initial version"`)                                        |
| `--description`           | Optional prompt description                                                                                  |
| `--model`                 | Default model name for this version                                                                          |
| `--invocation-params`     | JSON file path or inline JSON with invocation parameters (e.g. `temperature`, `max_tokens`, `top_p`, `stop`) |
| `--provider-params`       | JSON file path or inline JSON with provider-specific parameters (e.g. Azure deployment name, Bedrock region) |
| `--output`, `-o`          | Output format (`table`, `json`, `csv`, `parquet`) or file path                                               |
| `--verbose`, `-v`         | Enable verbose logs                                                                                          |

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`, `-s`   | 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`)           |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path   |
| `--verbose`, `-v` | Enable verbose logs                                              |

**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`, `-s`   | Space name or ID (required when using prompt name instead of ID) |
| `--description`   | Updated description for the prompt                               |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path   |
| `--verbose`, `-v` | Enable verbose logs                                              |

**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`, `-s`   | Space name or ID (required when using prompt name instead of ID) |
| `--force`, `-f`   | Skip the confirmation prompt                                     |
| `--verbose`, `-v` | Enable verbose logs                                              |

**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`, `-s`   | Space name or ID (required when using prompt name instead of ID) |
| `--limit`, `-l`   | Maximum number of versions to return (default: 15)               |
| `--cursor`, `-c`  | Pagination cursor for the next page                              |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path   |
| `--verbose`, `-v` | Enable verbose logs                                              |

**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                                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `--provider`              | LLM provider: `open_ai`, `azure_open_ai`, `aws_bedrock`, `vertex_ai`, `anthropic`, `custom` — required       |
| `--input-variable-format` | Variable interpolation format: `f_string`, `mustache`, `none` — required                                     |
| `--messages`              | Path to a JSON file, or inline JSON array of message objects — required                                      |
| `--space`, `-s`           | Space name or ID (required when using prompt name instead of ID)                                             |
| `--commit-message`        | Commit message describing this version (default: `"New version"`)                                            |
| `--model`                 | Default model name for this version                                                                          |
| `--invocation-params`     | JSON file path or inline JSON with invocation parameters (e.g. `temperature`, `max_tokens`, `top_p`, `stop`) |
| `--provider-params`       | JSON file path or inline JSON with provider-specific parameters (e.g. Azure deployment name, Bedrock region) |
| `--output`, `-o`          | Output format (`table`, `json`, `csv`, `parquet`) or file path                                               |
| `--verbose`, `-v`         | Enable verbose logs                                                                                          |

**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`) — required  |
| `--space`, `-s`   | Space name or ID (required when using prompt name instead of ID) |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path   |
| `--verbose`, `-v` | Enable verbose logs                                              |

**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> ...]
```

| Option            | Description                                                                                               |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| `--label`         | Label name to assign — required, repeat for multiple labels. Replaces all existing labels on the version. |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path                                            |
| `--verbose`, `-v` | Enable verbose logs                                                                                       |

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

| Option            | Description                                                    |
| ----------------- | -------------------------------------------------------------- |
| `--label`         | Label name to remove (e.g. `production`, `staging`) — required |
| `--verbose`, `-v` | Enable verbose logs                                            |

**Example:**

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