# kindgi suggested-changes > Suggested changes: new content for a data block in what a project runs; checked on the project's test cases, then pinned through the project's release gate, or added as the project's Latest; its block version written into the pack's files, or opened as a pull request (list / get / create / check / pin / add-as-latest / pull / withdraw) ## `kindgi suggested-changes` **Synopsis** ```sh signature kindgi suggested-changes ``` Suggested changes: new content for a data block in what a project runs; checked on the project's test cases, then pinned through the project's release gate, or added as the project's Latest; its block version written into the pack's files, or opened as a pull request (list / get / create / check / pin / add-as-latest / pull / withdraw). **Commands** | Command | Description | | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`kindgi suggested-changes list`](https://docs.kindgi.com/v0.4.0/reference/cli/suggested-changes.md#kindgi-suggested-changes-list) | List suggested changes, newest first: only those of agents you can read. | | [`kindgi suggested-changes get`](https://docs.kindgi.com/v0.4.0/reference/cli/suggested-changes.md#kindgi-suggested-changes-get) | Show a suggested change: its change (the block's content before and after), status, version, and its check: how its version and the version it's built on did on the project's test cases. | | [`kindgi suggested-changes create`](https://docs.kindgi.com/v0.4.0/reference/cli/suggested-changes.md#kindgi-suggested-changes-create) | Make a suggested change by hand: new content for one block in what the project runs (settings values, or the agent's instructions). | | [`kindgi suggested-changes check`](https://docs.kindgi.com/v0.4.0/reference/cli/suggested-changes.md#kindgi-suggested-changes-check) | Check a suggested change again on the project's test cases, frozen now, so new corrections count: its version and the version it's built on run the same cases. | | [`kindgi suggested-changes pin`](https://docs.kindgi.com/v0.4.0/reference/cli/suggested-changes.md#kindgi-suggested-changes-pin) | Pin a suggested change's version for its project, through the project's release gate with its check. | | [`kindgi suggested-changes add-as-latest`](https://docs.kindgi.com/v0.4.0/reference/cli/suggested-changes.md#kindgi-suggested-changes-add-as-latest) | Add a suggested change's version as its project's Latest, for a project that runs its Latest: the project runs it from now on, with no release gate. | | [`kindgi suggested-changes pull`](https://docs.kindgi.com/v0.4.0/reference/cli/suggested-changes.md#kindgi-suggested-changes-pull) | Write a suggested change's block version into the pack's block file, as `kindgi blocks pull` writes what runs: when it's newer than the file's, and the file holds no version newer than the one the change is built on, nor its own version with edits. | | [`kindgi suggested-changes withdraw`](https://docs.kindgi.com/v0.4.0/reference/cli/suggested-changes.md#kindgi-suggested-changes-withdraw) | Withdraw a suggested change: while `checking`, `check-failed` or `ready`, not while a second person decides its pin. | **See also** - [Fix what the experts corrected](https://docs.kindgi.com/v0.4.0/guides/improve/fix-what-experts-corrected.md) - [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md) ### `kindgi suggested-changes list` **Synopsis** ```sh signature kindgi suggested-changes list [--agent=] [--project=] [--status=] [--limit=] [--cursor=] [--table] ``` List suggested changes, newest first: only those of agents you can read. A status filter is applied after the page is read, so a page can hold fewer than --limit. **Options** | Option | Default | Description | | ------------------- | -------------------- | ----------------------------------------------------------------------------------------------------- | | `--agent ` | none | Only this agent's suggested changes. | | `--cursor ` | none | The next page, from `nextCursor`. | | `--limit ` | `25` (at most `100`) | Page size. | | `--project ` | none | Only the suggested changes for this project. | | `--status ` | none | One of: checking, check-failed, ready, waiting-for-second-person, pinned, added-as-latest, withdrawn. | Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** From [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md): ```sh pnpm exec kindgi suggested-changes list --agent=acme.rank.scorer --project= --table ``` **See also** - [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md) - [`kindgi suggested-changes`](https://docs.kindgi.com/v0.4.0/reference/cli/suggested-changes.md#kindgi-suggested-changes) ### `kindgi suggested-changes get` **Synopsis** ```sh signature kindgi suggested-changes get ``` Show a suggested change: its change (the block's content before and after), status, version, and its check: how its version and the version it's built on did on the project's test cases. A correction it fixes that its author has replaced since is named on stderr, with the live one that replaced it. **Options** Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** From [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md): ```sh pnpm exec kindgi suggested-changes get ``` **See also** - [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md) - [`kindgi suggested-changes`](https://docs.kindgi.com/v0.4.0/reference/cli/suggested-changes.md#kindgi-suggested-changes) ### `kindgi suggested-changes create` **Synopsis** ```sh signature kindgi suggested-changes create --agent= --project= --block= (--values=|@ | --template=|@) --why= [--fixes=]… ``` Make a suggested change by hand: new content for one block in what the project runs (settings values, or the agent's instructions). Its block version and agent version are made, and it's checked on the project's test cases: it's `checking`. The same change on the same version for the same project returns the suggested change made before. Needs `publish` on the agent. **Options** | Option | Default | Description | | --------------------------- | -------- | ------------------------------------------------------------------------- | | `--agent ` | required | The agent. | | `--block ` | required | The data block to change; the project's version must pin it. | | `--fixes ` | none | A correction the change fixes (repeatable). Repeatable. | | `--idempotency-key ` | none | A retry with the same key returns the first call's result. | | `--project ` | required | The project it's for: it's built on what the project runs. | | `--template ` | none | The agent's instructions (a prompt block), new text: inline or `@`. | | `--values ` | none | A settings block's new values: a JSON object, inline or `@`. | | `--why ` | required | What the change should fix, and why. | Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** From [Fix what the experts corrected](https://docs.kindgi.com/v0.4.0/guides/improve/fix-what-experts-corrected.md): ```sh pnpm exec kindgi suggested-changes create --agent=acme-store.refunds --project= \ ``` From [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md): ```sh pnpm exec kindgi suggested-changes create --agent=acme.rank.scorer --project= \ ``` **See also** - [Fix what the experts corrected](https://docs.kindgi.com/v0.4.0/guides/improve/fix-what-experts-corrected.md) - [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md) - [`kindgi suggested-changes`](https://docs.kindgi.com/v0.4.0/reference/cli/suggested-changes.md#kindgi-suggested-changes) ### `kindgi suggested-changes check` **Synopsis** ```sh signature kindgi suggested-changes check [--wait] ``` Check a suggested change again on the project's test cases, frozen now, so new corrections count: its version and the version it's built on run the same cases. When the project now runs another version, it's rebuilt on that version first. The suggested change is `checking`, then `ready` (its check says how each did) or `check-failed`. Allowed when `ready` or `check-failed`. Needs `publish` on the agent. **Options** | Option | Default | Description | | --------------------------- | ------- | ----------------------------------------------------------------------------------- | | `--idempotency-key ` | none | A retry with the same key returns the first call's result. | | `--wait` | off | Wait until the check is done (at most 30 minutes), then print the suggested change. | Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** From [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md): ```sh pnpm exec kindgi suggested-changes check --wait ``` **See also** - [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md) - [`kindgi suggested-changes`](https://docs.kindgi.com/v0.4.0/reference/cli/suggested-changes.md#kindgi-suggested-changes) ### `kindgi suggested-changes pin` **Synopsis** ```sh signature kindgi suggested-changes pin [--reason=] [--stop-following-latest] ``` Pin a suggested change's version for its project, through the project's release gate with its check. It prints the pin's answer: the pin, its test runs, the corrections a reused run marked `fixed` or reopened, and the suggested change under `suggestedChange`, `pinned` or `waiting-for-second-person` (a reviewer decides the approval: `kindgi approvals complete`). A refusal by the release gate lists every check, and leaves it `ready`. A project that follows Latest is refused (`409 pin-stops-latest`) unless --stop-following-latest; `kindgi suggested-changes add-as-latest` adds it as the project's Latest instead. Under `kindgi dev`, where a pin writes the version into the pack's files, it says on stderr which of the files it writes over that git hasn't committed, or that the pack isn't in git, from the pin check it asks first. Allowed when `ready`. Needs `pin` on the agent. **Options** | Option | Default | Description | | --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--idempotency-key ` | none | A retry with the same key returns the first call's result. | | `--reason ` | none | Why, kept on the request to pin it. | | `--stop-following-latest` | off | Pin even when it takes a project that follows Latest off it: that project then runs the pinned version, and no longer takes each new Latest. Without it, such a pin is refused (`409 pin-stops-latest`). | Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** From [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md): ```sh pnpm exec kindgi suggested-changes pin --reason="Fit first: 25 of 27 against 23." ``` **See also** - [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md) - [`kindgi suggested-changes`](https://docs.kindgi.com/v0.4.0/reference/cli/suggested-changes.md#kindgi-suggested-changes) ### `kindgi suggested-changes add-as-latest` **Synopsis** ```sh signature kindgi suggested-changes add-as-latest [--reason=] ``` Add a suggested change's version as its project's Latest, for a project that runs its Latest: the project runs it from now on, with no release gate. The suggested change is `added-as-latest`. Allowed when `ready`. Needs `pin` on the agent. **Options** | Option | Default | Description | | --------------------------- | ------- | ---------------------------------------------------------- | | `--idempotency-key ` | none | A retry with the same key returns the first call's result. | | `--reason ` | none | Why, kept on its `addedAsLatest`. | Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** From [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md): ```sh pnpm exec kindgi suggested-changes add-as-latest --reason="Fit first for acme." ``` **See also** - [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md) - [`kindgi suggested-changes`](https://docs.kindgi.com/v0.4.0/reference/cli/suggested-changes.md#kindgi-suggested-changes) ### `kindgi suggested-changes pull` **Synopsis** ```sh signature kindgi suggested-changes pull [--pr] [--project=] [--path=] ``` Write a suggested change's block version into the pack's block file, as `kindgi blocks pull` writes what runs: when it's newer than the file's, and the file holds no version newer than the one the change is built on, nor its own version with edits. Allowed when `ready`, `waiting-for-second-person`, `pinned` or `added-as-latest`. With --pr, in the pack's git repository: a new branch `kindgi/-` from the one checked out, a commit of the block files alone, a push, and a pull request opened with `gh` (without gh, where to open one: its URL, when the remote gives one). The corrections it fixes that are still `open` are then `being-fixed`, linked to the pull request (needs `publish` on the agent, or `write` in the correction's project for an agent that several projects serve). The pull request says only fixed words and numbers: never the suggested change's why, nor a correction's words. **Options** | Option | Default | Description | | ------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--path ` | the current directory | The pack directory. Default: the current one. | | `--pr` | off | Also make a branch, commit, push, and open a pull request; then mark the corrections it fixes `being-fixed`, linked to it. Refused when the pack isn't in git, or its block files have changes that aren't committed. | | `--project ` | none | Refuse unless the suggested change is for this project (an id or slug). | Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** From [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md): ```sh pnpm exec kindgi suggested-changes pull --pr ``` **See also** - [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md) - [`kindgi suggested-changes`](https://docs.kindgi.com/v0.4.0/reference/cli/suggested-changes.md#kindgi-suggested-changes) ### `kindgi suggested-changes withdraw` **Synopsis** ```sh signature kindgi suggested-changes withdraw --reason= ``` Withdraw a suggested change: while `checking`, `check-failed` or `ready`, not while a second person decides its pin. Needs `publish` on the agent. **Options** | Option | Default | Description | | --------------------------- | -------- | ---------------------------------------------------------- | | `--idempotency-key ` | none | A retry with the same key returns the first call's result. | | `--reason ` | required | Why, kept on the record (required). | Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** From [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md): ```sh pnpm exec kindgi suggested-changes withdraw --reason="Superseded by a better draft" ``` **See also** - [Suggest a change, and test it](https://docs.kindgi.com/v0.4.0/guides/improve/suggest-a-change.md) - [`kindgi suggested-changes`](https://docs.kindgi.com/v0.4.0/reference/cli/suggested-changes.md#kindgi-suggested-changes)