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

> ## Agent Instructions
> To set Ambral up in a project, run `npx ambral@latest skill install` in the project's root. It installs Ambral's skill, matched to the CLI's version, and the skill says how to do everything these pages describe with the `ambral` CLI. Prefer it to working from these pages. Never ask anyone for an Ambral API key, and never handle one: the person creates it in the web app and stores it where their app reads its secrets.

# ambral workloads

> Create, list and show the org's workloads, retitle and relabel them, change their model pools, and choose the model that serves each

Create, list and show the org's workloads, retitle and relabel them, change their model pools, and choose the model that serves each

Every ambral command also takes the [global flags](https://docs.ambral.ai/cli/reference/global-flags.md).

## ambral workloads create

```text theme={null}
ambral workloads create [flags] <name>
```

Create a workload: the name an agent's requests send in `x-workload`, and the model it serves

| Argument | Takes | Description |
| - | - | - |
| `<name>` | string | The workload's name, as its requests send it in `x-workload` |

| Flag | Takes | Description |
| - | - | - |
| `--model` | string; required | The catalog model it serves first: its primary, and its pool's only model |
| `--title` | string | A readable name for people, up to 100 characters, which a generated name can't give |
| `--label` | string; repeatable | A label, `k=v`, or `k` for a bare tag; repeat it for more, each key once |

**Examples**

```sh theme={null}
# A workload serving one catalog model
ambral workloads create support-agent --model anthropic/claude-haiku-5.5

# A generated workload, titled for people and labelled to be found
ambral workloads create agent-3f9c2a1e --model anthropic/claude-haiku-5.5 --title "Acme · onboarding agent" --label customer=acme --label beta
```

## ambral workloads list

```text theme={null}
ambral workloads list [flags]
```

List the org's workloads, by name, a page at a time with how many there are, with each one's title, primary model and pool

| Flag | Takes | Description |
| - | - | - |
| `--label` | string; repeatable | Only those labelled so: `k=v` for that value, `k` for any value; repeat it, and each must hold |
| `--cursor` | string | Start after this workload: the `next` a page before printed, with the same `--label` |

**Examples**

```sh theme={null}
# Only the workloads labelled customer=acme
ambral workloads list --label customer=acme
```

## ambral workloads get

```text theme={null}
ambral workloads get [flags] <name>
```

Show a workload: its primary model, its pool, how an agent connects to it through the Gateway, and its production over `--range`: how many sessions started, how many a run replayed, production's median score where a run scored it, the Gateway's requests and errors, a session's median turns, tokens and duration, and how many sessions each model served

| Argument | Takes | Description |
| - | - | - |
| `<name>` | string | The workload's name, as its requests send it in `x-workload` |

| Flag | Takes | Description |
| - | - | - |
| `--range` | `24h` \| `7d` \| `30d`; default `7d` | How far back its production section reads: `24h`, `7d` (the default) or `30d` |

**Examples**

```sh theme={null}
# Its production over the last day
ambral workloads get support-agent --range 24h

# As JSON
ambral workloads get support-agent --json
```

## ambral workloads update

```text theme={null}
ambral workloads update [flags] <name>
```

Change a workload's title or labels. Its name stays: a title is how a generated name gets a readable one

| Argument | Takes | Description |
| - | - | - |
| `<name>` | string | The workload's name, as its requests send it in `x-workload` |

| Flag | Takes | Description |
| - | - | - |
| `--title` | string | Its new title, up to 100 characters |
| `--clear-title` | | Clear its title |
| `--label` | string; repeatable | A label, `k=v`, or `k` for a bare tag; repeat it for more, each key once |
| `--unlabel` | string; repeatable | A label's key, to remove it; repeat it for more |

**Examples**

```sh theme={null}
# Retitle a workload, set one label and remove another, keeping the rest
ambral workloads update agent-3f9c2a1e --title "Acme · billing agent" --label tier=enterprise --unlabel beta

# Clear its title, so lists show its name alone
ambral workloads update agent-3f9c2a1e --clear-title
```

## ambral workloads set-primary

```text theme={null}
ambral workloads set-primary [flags] <name> <model>
```

Choose the model in a workload's pool that serves it: promote a candidate, or roll back

| Argument | Takes | Description |
| - | - | - |
| `<name>` | string | The workload's name, as its requests send it in `x-workload` |
| `<model>` | string | A catalog model's id, as `ambral models list` shows it |

**Examples**

```sh theme={null}
# Promote a candidate that won its run
ambral workloads set-primary support-agent openai/gpt-6-luna

# Roll back to the model it served before
ambral workloads set-primary support-agent anthropic/claude-haiku-5.5
```

## ambral workloads pool add

```text theme={null}
ambral workloads pool add [flags] <name> <model>
```

Add a catalog model to a workload's pool, so a run can score it as a candidate

| Argument | Takes | Description |
| - | - | - |
| `<name>` | string | The workload's name, as its requests send it in `x-workload` |
| `<model>` | string | A catalog model's id, as `ambral models list` shows it |

**Examples**

```sh theme={null}
# Make a model a candidate for support-agent
ambral workloads pool add support-agent openai/gpt-6-luna
```

## ambral workloads pool remove

```text theme={null}
ambral workloads pool remove [flags] <name> <model>
```

Remove a model from a workload's pool; its primary stays

| Argument | Takes | Description |
| - | - | - |
| `<name>` | string | The workload's name, as its requests send it in `x-workload` |
| `<model>` | string | A catalog model's id, as `ambral models list` shows it |


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