> ## 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 tasksets

> Create and read a workload's tasksets, line their runs up by run or by model, set how they're scored, and read the prompts their traces open with

Create and read a workload's tasksets, line their runs up by run or by model, set how they're scored, and read the prompts their traces open with

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

## ambral tasksets create

```text theme={null}
ambral tasksets create [flags] <taskset>
```

Create a taskset of a workload's recorded traces. Each trace's branch is fixed when it is created, so every run of it replays the same sessions

| Argument | Takes | Description |
| - | - | - |
| `<taskset>` | string | The taskset, as `<workload>/<taskset>`: its workload's name, then its own. A taskset's name is spelled as a workload's: lowercase letters, digits, `.`, `_` and `-`, starting with a letter or digit, at most 63 characters |

| Flag | Takes | Description |
| - | - | - |
| `--traces` | string; required | The workload's recorded traces, separated by commas, each as `ambral traces list` shows it (tr\_…, its latest branch with a reply) or one of its branches as `ambral traces get` names them (tr\_…:\<node>) |

**Examples**

```sh theme={null}
# A taskset of one trace's latest branch and another's branch ending at node 17
ambral tasksets create support-agent/refunds --traces tr_3f9a0c1b7e22a5d4,tr_81c2d0e4f5a6b7c8:17
```

## ambral tasksets list

```text theme={null}
ambral tasksets list [flags] [<workload>]
```

List the org's tasksets, or one workload's, newest first, a page at a time with how many there are: each one's kind, how many tasks it holds, its scoring version, its last run not marked local with how it went, and how many of its runs are marked local

| Argument | Takes | Description |
| - | - | - |
| `<workload>` | string; optional | Only this workload's tasksets |

| Flag | Takes | Description |
| - | - | - |
| `--sort` | `newest` \| `name` | The order: `newest` first (the default), or by `name`, each workload's in turn |
| `--cursor` | string | Start after this taskset: the `next` a page before printed, with the same `--sort` |

**Examples**

```sh theme={null}
# support-agent's tasksets
ambral tasksets list support-agent
```

## ambral tasksets get

```text theme={null}
ambral tasksets get [flags] <taskset>
```

Show a taskset and a page of its tasks: a replay taskset's traces' branches, or an offline taskset's scenarios, and its scoring version

| Argument | Takes | Description |
| - | - | - |
| `<taskset>` | string | The taskset, as `<workload>/<taskset>`: its workload's name, then its own. A taskset's name is spelled as a workload's: lowercase letters, digits, `.`, `_` and `-`, starting with a letter or digit, at most 63 characters |

| Flag | Takes | Description |
| - | - | - |
| `--cursor` | string | Start past this task: the `next` a page before printed |

**Examples**

```sh theme={null}
# As JSON
ambral tasksets get support-agent/refunds --json
```

## ambral tasksets results

```text theme={null}
ambral tasksets results [flags] <taskset>
```

Line a taskset's runs up side by side, by run (what changed over time on one model) or by model (where each model breaks): each column's counts, a row per scenario (or a replay taskset's branch) with each column's repeats passed, and each check's mean. Runs marked `local` are left out unless asked for (`--source`), and counted

| Argument | Takes | Description |
| - | - | - |
| `<taskset>` | string | The taskset, as `<workload>/<taskset>`: its workload's name, then its own. A taskset's name is spelled as a workload's: lowercase letters, digits, `.`, `_` and `-`, starting with a letter or digit, at most 63 characters |

| Flag | Takes | Description |
| - | - | - |
| `--by` | `run` \| `model`; required | A column each run of one model (`run`), or each model's newest completed run (`model`) |
| `--runs` | string | By run: these runs, separated by commas, in place of the newest (at most 12) |
| `--last` | integer | By run: how many of the newest runs to show, at most 12 (the default) |
| `--model` | string | By run: whose runs, a model's id or `production`; the newest run's when not given |
| `--models` | string | By model: only these, separated by commas, at most 6; the cheapest 6 when not given |
| `--label` | string; repeatable | Only those labelled so: `k=v` for that value, `k` for any value; repeat it, and each must hold |
| `--since` | date | Only runs started at or after this date or time, UTC (`2026-11-01`); not with `--runs` |
| `--source` | `not-local` \| `ci` \| `local` \| `all` | Which runs by where their suite ran: by default every run but those marked `local`; `all` reads them too. Not with `--runs`, which names the runs |
| `--scenario` | string | Only scenarios whose id starts so (`refunds/`) |
| `--check` | string | Only this check's: each cell its mean score |
| `--depth` | integer | One row for each start of the scenarios' ids this many segments long, split on `/` and `>` |
| `--only` | `differ` \| `mixed` \| `failing` \| `added` \| `changed` \| `fell` | Only rows where: `differ`, two columns passed different counts of repeats; `mixed`, a column passed some repeats and failed others; `failing`, some repeat failed; and by run, `added`, a column ran it and the one before didn't; `changed`, a column ran another revision of its task than the one before; `fell`, a column passed fewer than the one before. Two columns compare only where both ran the same revision of the task the same number of times. Where the suite gave no verdict, scores stand in |
| `--sort` | `passes` \| `id` | The rows' order: the fewest passes first (the default), or by id |
| `--cursor` | string | Start past this row: the `next` a page before printed, with the same flags |

**Examples**

```sh theme={null}
# Each model's newest completed run, cheapest first
ambral tasksets results support-agent/refunds-scenarios --by model

# The main branch's runs, only the scenarios that passed fewer repeats than in the run before
ambral tasksets results support-agent/refunds-scenarios --by run --label branch=main --only fell

# A pull request's run beside the base branch's
ambral tasksets results support-agent/refunds-scenarios --by run --runs <this run>,<base run>
```

## ambral tasksets scoring preset

```text theme={null}
ambral tasksets scoring preset [flags] [<name>]
```

List the scoring presets, each with when to use it, or print one as a YAML scoring config to start from, every field explained in a comment above it

| Argument | Takes | Description |
| - | - | - |
| `<name>` | `balanced` \| `criteria` \| `trajectory` \| `strict`; optional | The preset to print. Without one, every preset is listed, with when to use it |

| Flag | Takes | Description |
| - | - | - |
| `--judge` | string | The catalog model the preset's judges ask, as `ambral models list` shows it: required by a preset with judges, and taken by no other |

**Examples**

```sh theme={null}
# List the presets
ambral tasksets scoring preset

# Start a scoring file from the balanced preset, its judges asking that model
ambral tasksets scoring preset balanced --judge anthropic/claude-haiku-5.5 > evals/support-agent/refunds.yaml
```

## ambral tasksets scoring get

```text theme={null}
ambral tasksets scoring get [flags] <taskset>
```

Print a taskset's current scoring config as YAML, every field explained in a comment above it. It is whole: every key a file may leave out is written at its default

| Argument | Takes | Description |
| - | - | - |
| `<taskset>` | string | The taskset, as `<workload>/<taskset>`: its workload's name, then its own. A taskset's name is spelled as a workload's: lowercase letters, digits, `.`, `_` and `-`, starting with a letter or digit, at most 63 characters |

**Examples**

```sh theme={null}
# Write the saved version back out to its file, to edit
ambral tasksets scoring get support-agent/refunds > evals/support-agent/refunds.yaml
```

## ambral tasksets scoring set

```text theme={null}
ambral tasksets scoring set [flags] <taskset>
```

Save a scoring config as a taskset's next version, after checking it. A config with mistakes prints each, at its field, and saves nothing

| Argument | Takes | Description |
| - | - | - |
| `<taskset>` | string | The taskset, as `<workload>/<taskset>`: its workload's name, then its own. A taskset's name is spelled as a workload's: lowercase letters, digits, `.`, `_` and `-`, starting with a letter or digit, at most 63 characters |

| Flag | Takes | Description |
| - | - | - |
| `--file` | file; required | The scoring config: a .yaml, .yml or .json file, as `preset` and `get` print it |
| `--check` | | Check the config, the catalog's models included, without saving it |

**Examples**

```sh theme={null}
# Check the file, saving nothing
ambral tasksets scoring set support-agent/refunds --file evals/support-agent/refunds.yaml --check

# Save it as the next version
ambral tasksets scoring set support-agent/refunds --file evals/support-agent/refunds.yaml
```

## ambral tasksets prompts list

```text theme={null}
ambral tasksets prompts list [flags] <taskset>
```

List the system prompts the taskset's traces open with, the most traces first: each one's id, how many traces open with it, and its first line, and how many open with none

| Argument | Takes | Description |
| - | - | - |
| `<taskset>` | string | The taskset, as `<workload>/<taskset>`: its workload's name, then its own. A taskset's name is spelled as a workload's: lowercase letters, digits, `.`, `_` and `-`, starting with a letter or digit, at most 63 characters |

| Flag | Takes | Description |
| - | - | - |
| `--cursor` | string | Start after this prompt: the `next` a page before printed |

**Examples**

```sh theme={null}
# The prompts support-agent/refunds' traces open with
ambral tasksets prompts list support-agent/refunds
```


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