# kindgi improve > Improve: the runtime looking for better wording or settings, in Improve runs ## `kindgi improve` **Synopsis** ```sh signature kindgi improve ``` Improve: the runtime looking for better wording or settings, in Improve runs. **Commands** | Command | Description | | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | [`kindgi improve runs`](https://docs.kindgi.com/v0.4.0/reference/cli/improve.md#kindgi-improve-runs) | Improve runs: the runtime looking for better wording or settings for an agent in a project (start / list / get / cancel). | **See also** - [Improve an agent](https://docs.kindgi.com/v0.4.0/guides/improve/improve-an-agent.md) ### `kindgi improve runs` **Synopsis** ```sh signature kindgi improve runs ``` Improve runs: the runtime looking for better wording or settings for an agent in a project (start / list / get / cancel). **Commands** | Command | Description | | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`kindgi improve runs start`](https://docs.kindgi.com/v0.4.0/reference/cli/improve.md#kindgi-improve-runs-start) | Start an Improve run for an agent in a project. | | [`kindgi improve runs list`](https://docs.kindgi.com/v0.4.0/reference/cli/improve.md#kindgi-improve-runs-list) | List Improve runs, newest first: only those of agents you can read. | | [`kindgi improve runs get`](https://docs.kindgi.com/v0.4.0/reference/cli/improve.md#kindgi-improve-runs-get) | Show an Improve run: the version it started from, how many candidates it tried, what that cost, the corrections it took, and what it found (the suggested change it wrote, or why none). | | [`kindgi improve runs cancel`](https://docs.kindgi.com/v0.4.0/reference/cli/improve.md#kindgi-improve-runs-cancel) | Stop a running Improve run: it ends `cancelled` and writes no suggested change. | **See also** - [Improve an agent](https://docs.kindgi.com/v0.4.0/guides/improve/improve-an-agent.md) - [`kindgi improve`](https://docs.kindgi.com/v0.4.0/reference/cli/improve.md#kindgi-improve) #### `kindgi improve runs start` **Synopsis** ```sh signature kindgi improve runs start --agent= --project= [--check] [--tier=prompt|settings]… [--objective=passRate|weightedPrecisionAtK] [--group-weights=as-recorded|experts-only] [--provider= --model=] [--drafts=] [--max-cost=] [--max-candidates=] [--wait] ``` Start an Improve run for an agent in a project. From the version the project runs, it tries new wording for the agent's prompt block (the prompt tier), new values for the settings it may tune (the settings tier), or both, on the project's test set, within a budget, learning from the project's corrections sorted to Improve. It keeps a change only when, on every case of the test set, it passes more cases than that version and fails none that passed, and writes it as a suggested change, which a reviewer decides (`kindgi suggested-changes pin`). `--check` says whether it's ready and what it's estimated to cost, and starts nothing; it exits 3 when it isn't ready. A start that isn't ready is refused, listing every missing item with its fix. Answers at once with the Improve run; `--wait` waits for its outcome. Needs `publish` on the agent. **Options** | Option | Default | Description | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--agent ` | required | The agent. | | `--check` | off | Whether it's ready, and what it's estimated to cost: every item it needs, each missing one with its fix, the estimate, and this month's spend against the Improve schedule's cap. Starts nothing. Exits 3 when it isn't ready. | | `--drafts ` | `3` (`1` to `5`; with `--tier=prompt` only) | For the prompt tier: how many drafts of the wording to write (1–5, default 3). | | `--group-weights ` | none (counts everyone until the project, its tenant, or the agent in the project has an expert group, then only those) | Which corrections the Improve run learns from: `as-recorded` (all groups) or `experts-only` (expert groups only). Omitted, it counts everyone until the project, its tenant, or the agent in the project has an expert group, then only those. | | `--idempotency-key ` | none | A retry with the same key returns the first call's result. | | `--max-candidates ` | `30` | The most candidates it tries (default 30). | | `--max-cost ` | `5` (US dollars) | The most its search may cost, in US dollars (default 5). The proof of its best change runs after the search and isn't capped by it. | | `--model ` | none (the model the version's model-settings block names drafts the wording; with `--provider`, for `--tier=prompt`) | For the prompt tier: the model that drafts the wording (with `--provider`). | | `--objective ` | `passRate` | How candidates that pass equally are ranked: `passRate` (the default) or `weightedPrecisionAtK`. | | `--project ` | required | The project the Improve run works in, by id: it starts from the version the project runs, and learns from and is proven on the project's test set. | | `--provider ` | none (with `--model`, for `--tier=prompt`) | For the prompt tier: the provider whose model drafts the wording (with `--model`). Left out, the provider and model the version's model-settings block names draft it; with neither, the prompt tier isn't ready. | | `--tier ` | every tier that's ready | What to try: `prompt`, new wording for the agent's prompt block (a drafted suggested change always waits for a reviewer), or `settings`, values for the settings it may tune. Repeat it for both. Left out, every tier that's ready. Repeatable. | | `--wait` | off | Wait until the Improve run is done (at most 30 minutes), then print it. | Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** From [Improve an agent](https://docs.kindgi.com/v0.4.0/guides/improve/improve-an-agent.md): ```sh pnpm exec kindgi improve runs start --agent=acme.rank.scorer --project= --check --table pnpm exec kindgi improve runs start --agent=acme.rank.scorer --project= --max-candidates=4 --wait ``` **See also** - [Improve an agent](https://docs.kindgi.com/v0.4.0/guides/improve/improve-an-agent.md) - [`kindgi improve runs`](https://docs.kindgi.com/v0.4.0/reference/cli/improve.md#kindgi-improve-runs) #### `kindgi improve runs list` **Synopsis** ```sh signature kindgi improve runs list [--agent=] [--project=] [--status=running|completed|failed|cancelled] [--limit=] [--cursor=] [--table] ``` List Improve runs, newest first: only those of agents you can read. `--table` shows each one's agent and the version it started from, its project, status, the candidates it tried, its cost and what it found. **Options** | Option | Default | Description | | ------------------- | -------------------- | ---------------------------------------------------------------------------------------- | | `--agent ` | none | Only this agent's Improve runs. | | `--cursor ` | none | The next page, from `nextCursor`. | | `--limit ` | `25` (at most `100`) | Page size. | | `--project ` | none | Only the Improve runs in this project, by id. | | `--status ` | none | Only the Improve runs with this status: `running`, `completed`, `failed` or `cancelled`. | Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** From [Improve an agent](https://docs.kindgi.com/v0.4.0/guides/improve/improve-an-agent.md): ```sh pnpm exec kindgi improve runs list --project= --table ``` **See also** - [Improve an agent](https://docs.kindgi.com/v0.4.0/guides/improve/improve-an-agent.md) - [`kindgi improve runs`](https://docs.kindgi.com/v0.4.0/reference/cli/improve.md#kindgi-improve-runs) #### `kindgi improve runs get` **Synopsis** ```sh signature kindgi improve runs get ``` Show an Improve run: the version it started from, how many candidates it tried, what that cost, the corrections it took, and what it found (the suggested change it wrote, or why none). **Options** Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** From [Improve an agent](https://docs.kindgi.com/v0.4.0/guides/improve/improve-an-agent.md): ```sh pnpm exec kindgi improve runs get ``` **See also** - [Improve an agent](https://docs.kindgi.com/v0.4.0/guides/improve/improve-an-agent.md) - [`kindgi improve runs`](https://docs.kindgi.com/v0.4.0/reference/cli/improve.md#kindgi-improve-runs) #### `kindgi improve runs cancel` **Synopsis** ```sh signature kindgi improve runs cancel ``` Stop a running Improve run: it ends `cancelled` and writes no suggested change. **Options** | Option | Default | Description | | --------------------------- | ------- | ---------------------------------------------------------- | | `--idempotency-key ` | none | A retry with the same key returns the first call's result. | Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** From [Improve an agent](https://docs.kindgi.com/v0.4.0/guides/improve/improve-an-agent.md): ```sh pnpm exec kindgi improve runs cancel ``` **See also** - [Improve an agent](https://docs.kindgi.com/v0.4.0/guides/improve/improve-an-agent.md) - [`kindgi improve runs`](https://docs.kindgi.com/v0.4.0/reference/cli/improve.md#kindgi-improve-runs)