# kindgi agents

> Manage agent registrations and which version runs where

## `kindgi agents`

**Synopsis**

```sh signature
kindgi agents <command>
```

Manage agent registrations and which version runs where.

**Commands**

| Command                                                                                                              | Description                                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| [`kindgi agents list`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-list)                   | List registered agents (the latest version of each).                                                                                   |
| [`kindgi agents get`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-get)                     | Fetch a registered agent: its latest version, or the version given.                                                                    |
| [`kindgi agents publish`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-publish)             | Register an agent definition.                                                                                                          |
| [`kindgi agents derive`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-derive)               | Publish a new agent version from a pinned one with some prompt or settings pins swapped (no code change).                              |
| [`kindgi agents unregister`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-unregister)       | Unregister a specific agent version: runs stop using it.                                                                               |
| [`kindgi agents versions`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-versions)           | List the registered versions of an agent.                                                                                              |
| [`kindgi agents live`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-live)                   | Show the version a run of this agent would use for a project and segment path, and why: a live version (with its scope) or the latest. |
| [`kindgi agents live-versions`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-live-versions) | List every scope with a live version of this agent pinned.                                                                             |
| [`kindgi agents promote`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-promote)             | Make a version live for a scope: its runs that don't name a version use it, from the next run.                                         |
| [`kindgi agents gate-policy`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-gate-policy)     | Show the gate policy a promotion of this agent for a scope is checked against (the most specific scope with one), or null.             |
| [`kindgi agents rollback`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-rollback)           | Put a scope back on its previous live version, or on the version given.                                                                |
| [`kindgi agents unpin`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-unpin)                 | Remove a scope's own live version: its runs use the next scope up (or the latest when nothing is pinned).                              |
| [`kindgi agents promotions`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-promotions)       | The history of what was made live, rolled back or unpinned.                                                                            |

**See also**

- [Change a prompt or a setting without a deploy](https://docs.kindgi.com/v0.1.10/guides/evals/change-a-prompt-or-setting.md)
- [Live versions reference](https://docs.kindgi.com/v0.1.10/guides/evals/live-versions-reference.md)
- [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md)
- [Deploy your agent to Kindgi Cloud](https://docs.kindgi.com/v0.1.10/hosted/deploy-your-agent.md)

### `kindgi agents list`

**Synopsis**

```sh signature
kindgi agents list [--name=<prefix>] [--include-retired] [--limit=<n>] [--cursor=<c>]
```

List registered agents (the latest version of each).

**Options**

| Option              | Default              | Description                                                                                             |
| ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------- |
| `--cursor <value>`  | none                 | Resume after this cursor, from the previous page's `nextCursor`.                                        |
| `--include-retired` | off                  | Include retired agents (every version unregistered), each as its highest version with `unregisteredAt`. |
| `--limit <value>`   | `25` (at most `100`) | The most to return (default 25, at most 100).                                                           |
| `--name <value>`    | none                 | Only agents whose id starts with this.                                                                  |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

List the registered agents.

```sh
kindgi agents list
```

List agents whose id starts with a prefix, including retired ones.

```sh
kindgi agents list --name=acme-ops. --include-retired
```

**See also**

- [Change a prompt or a setting without a deploy](https://docs.kindgi.com/v0.1.10/guides/evals/change-a-prompt-or-setting.md)
- [Live versions reference](https://docs.kindgi.com/v0.1.10/guides/evals/live-versions-reference.md)
- [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md)
- [Deploy your agent to Kindgi Cloud](https://docs.kindgi.com/v0.1.10/hosted/deploy-your-agent.md)
- [`kindgi agents`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents)

### `kindgi agents get`

**Synopsis**

```sh signature
kindgi agents get <agent-id> [<version>]
```

Fetch a registered agent: its latest version, or the version given.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

Show an agent's latest version.

```sh
kindgi agents get acme-ops.reply-drafter
```

Show one specific version.

```sh
kindgi agents get acme-ops.reply-drafter 1.2.0
```

**See also**

- [Change a prompt or a setting without a deploy](https://docs.kindgi.com/v0.1.10/guides/evals/change-a-prompt-or-setting.md)
- [Live versions reference](https://docs.kindgi.com/v0.1.10/guides/evals/live-versions-reference.md)
- [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md)
- [Deploy your agent to Kindgi Cloud](https://docs.kindgi.com/v0.1.10/hosted/deploy-your-agent.md)
- [`kindgi agents`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents)

### `kindgi agents publish`

**Synopsis**

```sh signature
kindgi agents publish --spec=<json-or-@file> [--project=<project-id>]
```

Register an agent definition.

**Options**

| Option              | Default                      | Description                                                                          |
| ------------------- | ---------------------------- | ------------------------------------------------------------------------------------ |
| `--project <value>` | the tenant's Default project | The project to register the agent in, by id (default: the tenant's Default project). |
| `--spec <value>`    | required                     | The agent definition as JSON, or `@<file>` to read it from a file. Required.         |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

Register an agent definition from a file.

```sh
kindgi agents publish --spec=@agent.json
```

Register it in a named project.

```sh
kindgi agents publish --spec=@agent.json --project=<project-id>
```

**See also**

- [Change a prompt or a setting without a deploy](https://docs.kindgi.com/v0.1.10/guides/evals/change-a-prompt-or-setting.md)
- [Live versions reference](https://docs.kindgi.com/v0.1.10/guides/evals/live-versions-reference.md)
- [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md)
- [Deploy your agent to Kindgi Cloud](https://docs.kindgi.com/v0.1.10/hosted/deploy-your-agent.md)
- [`kindgi agents`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents)

### `kindgi agents derive`

**Synopsis**

```sh signature
kindgi agents derive <agent-id> --from=<semver> [--prompt=<block-id>=<version>]... [--setting=<block-id>=<version>]... [--label=<text>] [--project=<project-id>]
```

Publish a new agent version from a pinned one with some prompt or settings pins swapped (no code change).

**Options**

| Option              | Default                                                   | Description                                                                                                             |
| ------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `--from <value>`    | required                                                  | The agent version to derive from; it must be pinned. Required.                                                          |
| `--label <value>`   | none                                                      | A short label for the new version.                                                                                      |
| `--project <value>` | none                                                      | The agent's project, by id; only needed when the runtime doesn't record it on the version.                              |
| `--prompt <value>`  | none (at least one `--prompt` or `--setting` is required) | Pin a prompt block the version already uses to this version (`<block-id>=<version>`). Repeat for several. Repeatable.   |
| `--setting <value>` | none (at least one `--prompt` or `--setting` is required) | Pin a settings block the version already uses to this version (`<block-id>=<version>`). Repeat for several. Repeatable. |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Change a prompt or a setting without a deploy](https://docs.kindgi.com/v0.1.10/guides/evals/change-a-prompt-or-setting.md):

```sh
pnpm exec kindgi agents derive acme-ops.reply-drafter --from=1.0.0 --setting=acme.reply-style=1.1.0 --label="Refund limit 100"
```

**See also**

- [Change a prompt or a setting without a deploy](https://docs.kindgi.com/v0.1.10/guides/evals/change-a-prompt-or-setting.md)
- [`kindgi agents`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents)

### `kindgi agents unregister`

**Synopsis**

```sh signature
kindgi agents unregister <agent-id> <version>
```

Unregister a specific agent version: runs stop using it.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

Unregister one version of an agent, so runs stop using it.

```sh
kindgi agents unregister acme-ops.reply-drafter 1.2.0
```

**See also**

- [Change a prompt or a setting without a deploy](https://docs.kindgi.com/v0.1.10/guides/evals/change-a-prompt-or-setting.md)
- [Live versions reference](https://docs.kindgi.com/v0.1.10/guides/evals/live-versions-reference.md)
- [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md)
- [Deploy your agent to Kindgi Cloud](https://docs.kindgi.com/v0.1.10/hosted/deploy-your-agent.md)
- [`kindgi agents`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents)

### `kindgi agents versions`

**Synopsis**

```sh signature
kindgi agents versions <agent-id> [--include-unregistered] [--limit=<n>] [--cursor=<c>]
```

List the registered versions of an agent.

**Options**

| Option                   | Default              | Description                                                                        |
| ------------------------ | -------------------- | ---------------------------------------------------------------------------------- |
| `--cursor <value>`       | none                 | Resume after this cursor, from the previous page's `nextCursor`.                   |
| `--include-unregistered` | off                  | Include unregistered versions (each with `unregisteredAt`), a retired agent's too. |
| `--limit <value>`        | `25` (at most `100`) | The most to return (default 25, at most 100).                                      |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

List an agent's registered versions.

```sh
kindgi agents versions acme-ops.reply-drafter
```

Include unregistered versions too.

```sh
kindgi agents versions acme-ops.reply-drafter --include-unregistered
```

**See also**

- [Change a prompt or a setting without a deploy](https://docs.kindgi.com/v0.1.10/guides/evals/change-a-prompt-or-setting.md)
- [Live versions reference](https://docs.kindgi.com/v0.1.10/guides/evals/live-versions-reference.md)
- [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md)
- [Deploy your agent to Kindgi Cloud](https://docs.kindgi.com/v0.1.10/hosted/deploy-your-agent.md)
- [`kindgi agents`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents)

### `kindgi agents live`

**Synopsis**

```sh signature
kindgi agents live <agent-id> [--project=<project-id> [--segment=<key:value>]…]
```

Show the version a run of this agent would use for a project and segment path, and why: a live version (with its scope) or the latest.

**Options**

| Option              | Default | Description                                                                                                                         |
| ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--project <value>` | none    | The run's project, by id.                                                                                                           |
| `--segment <value>` | none    | One step of the segment path, `key:value` (e.g. `company:acme`); repeat it in order, coarse to fine. Needs `--project`. Repeatable. |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md):

```sh
pnpm exec kindgi agents live acme.order-desk --project=<project-id> --segment=company:acme
```

**See also**

- [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md)
- [`kindgi agents`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents)

### `kindgi agents live-versions`

**Synopsis**

```sh signature
kindgi agents live-versions <agent-id>
```

List every scope with a live version of this agent pinned.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

List every scope with a live version of the agent.

```sh
kindgi agents live-versions acme.order-desk
```

**See also**

- [Change a prompt or a setting without a deploy](https://docs.kindgi.com/v0.1.10/guides/evals/change-a-prompt-or-setting.md)
- [Live versions reference](https://docs.kindgi.com/v0.1.10/guides/evals/live-versions-reference.md)
- [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md)
- [Deploy your agent to Kindgi Cloud](https://docs.kindgi.com/v0.1.10/hosted/deploy-your-agent.md)
- [`kindgi agents`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents)

### `kindgi agents promote`

**Synopsis**

```sh signature
kindgi agents promote <agent-id> <version> (--tenant | --org=<org-id> | --project=<project-id> [--segment=<key:value>]…) [--eval-run=<eval-run-id>] [--reason=<text>] [--check]
```

Make a version live for a scope: its runs that don't name a version use it, from the next run. Open conversations keep their version. With a gate policy for the scope, the comparison named by --eval-run is checked first: the answer's `status` is `promoted`, or `pending-approval` (a reviewer approves it); a refusal lists every check. `--check` asks what would happen, changing nothing.

**Options**

| Option                      | Default                                           | Description                                                                                                                         |
| --------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--check`                   | off                                               | What the gate would say: would-promote, needs-approval or gate-failed. Changes nothing.                                             |
| `--eval-run <value>`        | none                                              | The comparison eval run the gate checks, kept on the record.                                                                        |
| `--idempotency-key <value>` | none                                              | A retry with the same key returns the first call's result.                                                                          |
| `--org <value>`             | required: one of `--tenant`, `--org`, `--project` | An org, by id.                                                                                                                      |
| `--project <value>`         | required: one of `--tenant`, `--org`, `--project` | A project, by id; with `--segment`, a segment in it.                                                                                |
| `--reason <value>`          | none                                              | Why, kept on the record.                                                                                                            |
| `--segment <value>`         | none                                              | One step of the segment path, `key:value` (e.g. `company:acme`); repeat it in order, coarse to fine. Needs `--project`. Repeatable. |
| `--tenant`                  | required: one of `--tenant`, `--org`, `--project` | The whole tenant.                                                                                                                   |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Live versions reference](https://docs.kindgi.com/v0.1.10/guides/evals/live-versions-reference.md):

```sh
pnpm exec kindgi agents promote acme.order-desk 1.0.0 --project=<project-id> --segment=company:globex --reason="Pin globex before its gate"
```

From [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md):

```sh
pnpm exec kindgi agents promote acme.order-desk 1.0.0 --tenant --reason="1.0.0 is the version we checked"
```

**See also**

- [Live versions reference](https://docs.kindgi.com/v0.1.10/guides/evals/live-versions-reference.md)
- [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md)
- [Deploy your agent to Kindgi Cloud](https://docs.kindgi.com/v0.1.10/hosted/deploy-your-agent.md)
- [`kindgi agents`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents)

### `kindgi agents gate-policy`

**Synopsis**

```sh signature
kindgi agents gate-policy <agent-id> (--tenant | --org=<org-id> | --project=<project-id> [--segment=<key:value>]…)
```

Show the gate policy a promotion of this agent for a scope is checked against (the most specific scope with one), or null.

**Options**

| Option              | Default                                           | Description                                                                                                                         |
| ------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--org <value>`     | required: one of `--tenant`, `--org`, `--project` | An org, by id.                                                                                                                      |
| `--project <value>` | required: one of `--tenant`, `--org`, `--project` | A project, by id; with `--segment`, a segment in it.                                                                                |
| `--segment <value>` | none                                              | One step of the segment path, `key:value` (e.g. `company:acme`); repeat it in order, coarse to fine. Needs `--project`. Repeatable. |
| `--tenant`          | required: one of `--tenant`, `--org`, `--project` | The whole tenant.                                                                                                                   |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

Show the gate policy for the whole tenant.

```sh
kindgi agents gate-policy acme.order-desk --tenant
```

Show the policy for a segment of a project.

```sh
kindgi agents gate-policy acme.order-desk --project=<project-id> --segment=company:acme
```

**See also**

- [Change a prompt or a setting without a deploy](https://docs.kindgi.com/v0.1.10/guides/evals/change-a-prompt-or-setting.md)
- [Live versions reference](https://docs.kindgi.com/v0.1.10/guides/evals/live-versions-reference.md)
- [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md)
- [Deploy your agent to Kindgi Cloud](https://docs.kindgi.com/v0.1.10/hosted/deploy-your-agent.md)
- [`kindgi agents`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents)

### `kindgi agents rollback`

**Synopsis**

```sh signature
kindgi agents rollback <agent-id> (--tenant | --org=<org-id> | --project=<project-id> [--segment=<key:value>]…) [--to=<semver>] [--reason=<text>]
```

Put a scope back on its previous live version, or on the version given.

**Options**

| Option                      | Default                                           | Description                                                                                                                         |
| --------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--idempotency-key <value>` | none                                              | A retry with the same key returns the first call's result.                                                                          |
| `--org <value>`             | required: one of `--tenant`, `--org`, `--project` | An org, by id.                                                                                                                      |
| `--project <value>`         | required: one of `--tenant`, `--org`, `--project` | A project, by id; with `--segment`, a segment in it.                                                                                |
| `--reason <value>`          | none                                              | Why, kept on the record.                                                                                                            |
| `--segment <value>`         | none                                              | One step of the segment path, `key:value` (e.g. `company:acme`); repeat it in order, coarse to fine. Needs `--project`. Repeatable. |
| `--tenant`                  | required: one of `--tenant`, `--org`, `--project` | The whole tenant.                                                                                                                   |
| `--to <value>`              | the previous live version                         | An earlier version to go back to (default: the previous one).                                                                       |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md):

```sh
pnpm exec kindgi agents rollback acme.order-desk --tenant --reason="1.2.0 answers worse"
```

**See also**

- [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md)
- [`kindgi agents`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents)

### `kindgi agents unpin`

**Synopsis**

```sh signature
kindgi agents unpin <agent-id> (--tenant | --org=<org-id> | --project=<project-id> [--segment=<key:value>]…) [--reason=<text>]
```

Remove a scope's own live version: its runs use the next scope up (or the latest when nothing is pinned).

**Options**

| Option                      | Default                                           | Description                                                                                                                         |
| --------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--idempotency-key <value>` | none                                              | A retry with the same key returns the first call's result.                                                                          |
| `--org <value>`             | required: one of `--tenant`, `--org`, `--project` | An org, by id.                                                                                                                      |
| `--project <value>`         | required: one of `--tenant`, `--org`, `--project` | A project, by id; with `--segment`, a segment in it.                                                                                |
| `--reason <value>`          | none                                              | Why, kept on the record.                                                                                                            |
| `--segment <value>`         | none                                              | One step of the segment path, `key:value` (e.g. `company:acme`); repeat it in order, coarse to fine. Needs `--project`. Repeatable. |
| `--tenant`                  | required: one of `--tenant`, `--org`, `--project` | The whole tenant.                                                                                                                   |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md):

```sh
pnpm exec kindgi agents unpin acme.order-desk --tenant --reason="Back to the latest"
```

**See also**

- [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md)
- [`kindgi agents`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents)

### `kindgi agents promotions`

**Synopsis**

```sh signature
kindgi agents promotions <command>
```

The history of what was made live, rolled back or unpinned.

**Commands**

| Command                                                                                                                  | Description                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| [`kindgi agents promotions list`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-promotions-list) | List an agent's promotions, rollbacks and unpins, newest first; name a scope for only its history. |
| [`kindgi agents promotions get`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-promotions-get)   | Fetch one promotion of an agent.                                                                   |

**See also**

- [Change a prompt or a setting without a deploy](https://docs.kindgi.com/v0.1.10/guides/evals/change-a-prompt-or-setting.md)
- [Live versions reference](https://docs.kindgi.com/v0.1.10/guides/evals/live-versions-reference.md)
- [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md)
- [Deploy your agent to Kindgi Cloud](https://docs.kindgi.com/v0.1.10/hosted/deploy-your-agent.md)
- [`kindgi agents`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents)

#### `kindgi agents promotions list`

**Synopsis**

```sh signature
kindgi agents promotions list <agent-id> [(--tenant | --org=<org-id> | --project=<project-id> [--segment=<key:value>]…)] [--limit=<n>] [--cursor=<c>]
```

List an agent's promotions, rollbacks and unpins, newest first; name a scope for only its history.

**Options**

| Option              | Default                                           | Description                                                                                                                         |
| ------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--cursor <value>`  | none                                              | Resume after this cursor, from the previous page's `nextCursor`.                                                                    |
| `--limit <value>`   | `25` (at most `100`)                              | The most to return (default 25, at most 100).                                                                                       |
| `--org <value>`     | none (no scope given: the history of every scope) | An org, by id.                                                                                                                      |
| `--project <value>` | none (no scope given: the history of every scope) | A project, by id; with `--segment`, a segment in it.                                                                                |
| `--segment <value>` | none                                              | One step of the segment path, `key:value` (e.g. `company:acme`); repeat it in order, coarse to fine. Needs `--project`. Repeatable. |
| `--tenant`          | none (no scope given: the history of every scope) | The whole tenant.                                                                                                                   |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Live versions reference](https://docs.kindgi.com/v0.1.10/guides/evals/live-versions-reference.md):

```sh
pnpm exec kindgi agents promotions list acme.order-desk --table
```

**See also**

- [Live versions reference](https://docs.kindgi.com/v0.1.10/guides/evals/live-versions-reference.md)
- [`kindgi agents promotions`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-promotions)

#### `kindgi agents promotions get`

**Synopsis**

```sh signature
kindgi agents promotions get <agent-id> <promotion-id>
```

Fetch one promotion of an agent.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

Show one promotion of an agent.

```sh
kindgi agents promotions get acme.order-desk <promotion-id>
```

**See also**

- [Change a prompt or a setting without a deploy](https://docs.kindgi.com/v0.1.10/guides/evals/change-a-prompt-or-setting.md)
- [Live versions reference](https://docs.kindgi.com/v0.1.10/guides/evals/live-versions-reference.md)
- [Release an agent version](https://docs.kindgi.com/v0.1.10/guides/evals/release-an-agent-version.md)
- [Deploy your agent to Kindgi Cloud](https://docs.kindgi.com/v0.1.10/hosted/deploy-your-agent.md)
- [`kindgi agents promotions`](https://docs.kindgi.com/v0.1.10/reference/cli/agents.md#kindgi-agents-promotions)