Skip to content

docs: feat(cli): deployment history and version-scoped diff/review #90

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AaronForinton merged 2 commits into from
Apr 20, 2026
Merged

docs: feat(cli): deployment history and version-scoped diff/review #90

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4d210bc
docs: auto-update from 0730d06
github-actions[bot] Apr 17, 2026
1cd5891
Merge branch 'main' into docs/auto-update-0730d06
AaronForinton Apr 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 71 additions & 12 deletions docs/docs/reference/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,21 +87,34 @@ poly status

Show differences between the local project and the remote version.

With no arguments, shows local changes against the remote version. Pass a version hash to compare that version against its predecessor. Use `--before` and `--after` to compare any two named versions, environments, or branches.

Examples:

~~~bash
poly diff
poly diff file1.yaml
poly diff sandbox
poly diff --before hash1 --after hash2
poly diff --files file1.yaml
~~~

#### `poly diff` flags

| Flag | Description |
|---|---|
| `hash` | Optional positional. Hash of the version to compare against its predecessor. Cannot be combined with `--before`/`--after`. |
| `--files` | List of files to show changes for. If not specified, shows all changes. |
| `--before` | Name of the original branch, environment, or version hash to compare with. If specified without `--after`, compares against the current local project. |
| `--after` | Name of the branch, environment, or version hash to compare against. If specified without `--before`, compares against the previous version. |

### `poly revert`

Revert local changes.
Revert local changes. With no arguments, reverts all changes. Pass specific files to revert only those.

Examples:

~~~bash
poly revert --all
poly revert
poly revert file1.yaml file2.yaml
~~~

Expand Down Expand Up @@ -164,9 +177,13 @@ Examples:

~~~bash
poly format
poly format file1.py
poly format --files file1.py
~~~

| Flag | Description |
|---|---|
| `--files` | Specific files or directories to format. If not specified, runs on the whole project tree. |

### `poly validate`

Validate project configuration locally.
Expand All @@ -177,18 +194,32 @@ poly validate

### `poly review`

Create a GitHub Gist of Agent Studio project changes to share with others.
Create and manage GitHub Gist diff reviews of Agent Studio project changes.

#### `poly review create`

Create a GitHub Gist for reviewing changes, similar to a pull request.

Running `poly review` without a subcommand creates a new gist comparing local changes against the remote project. Use `--before` and `--after` to compare two remote branches or versions. Use `--debug` to enable DEBUG-level logging for troubleshooting.
With no arguments, creates a gist comparing local changes against the remote project. Pass a version hash to review that version against its predecessor. Use `--before` and `--after` to compare any two named versions, environments, or branches.

Examples:

~~~bash
poly review
poly review --before main --after feature-branch
poly review --debug
poly review create
poly review create --path /path/to/project
poly review create version-hash-1
poly review create --before main --after feature-branch
poly review create --before sandbox --after live
poly review create --before version-hash-1 --after version-hash-2
~~~

| Flag | Description |
|---|---|
| `hash` | Optional positional. Hash of the version to compare against its predecessor. Cannot be combined with `--before`/`--after`. |
| `--before` | Name of the original branch, environment, or version hash to compare with. |
| `--after` | Name of the branch, environment, or version hash to compare against. |
| `--files` | List of files to include in the review. If not specified, includes all changes. |

#### `poly review list`

Interactively select a review gist and open it in the browser.
Expand All @@ -208,6 +239,32 @@ poly review delete --id GIST_ID
poly review delete --json
~~~

### `poly deployments`

Manage deployment history for the project.

#### `poly deployments list`

List deployment history for the project. Shows the most recent deployments for the specified environment, with Rich console output including sandbox / pre-release / live badges to indicate currently active versions.

Examples:

~~~bash
poly deployments list
poly deployments list --env live
poly deployments list --details
poly deployments list --limit 20 --offset 10
poly deployments list --hash abc123456
~~~

| Flag | Description |
|---|---|
| `--env`, `-e` | Environment to list deployments for. Choices: `sandbox`, `pre-release`, `live`. Defaults to `sandbox`. |
| `--limit` | Maximum number of versions to show. Defaults to `10`. |
| `--offset` | Number of versions to skip before showing results. Defaults to `0`. |
| `--hash` | Start listing from this version hash (overrides `--offset`). |
| `--details` | Print full metadata for each deployment instead of the compact table view. |

### `poly chat`

Start an interactive chat session with your agent, or run scripted/automated conversations.
Expand Down Expand Up @@ -319,7 +376,7 @@ poly push --json
poly pull --json
poly validate --json
poly diff --json
poly revert --json --all
poly revert --json
poly branch list --json
poly branch create my-feature --json
poly branch switch my-feature --json
Expand All @@ -330,6 +387,7 @@ poly format --json
poly init --region us-1 --account_id 123 --project_id my_project --json
poly chat --json -m 'Hello'
poly chat --json --input-file ./script.txt
poly deployments list --json
~~~

When `--json` is used:
Expand All @@ -348,7 +406,7 @@ The exact fields vary by command. Common fields include:
| `poly push --json` | `success`, `message`, `dry_run` |
| `poly pull --json` | `success`, `files_with_conflicts` |
| `poly validate --json` | `valid`, `errors` |
| `poly diff --json` | `diffs` |
| `poly diff --json` | `success`, `diffs` |
| `poly revert --json` | `success`, `files_reverted` |
| `poly branch list --json` | `current_branch`, `branches` |
| `poly branch create --json` | `success`, `new_branch_id`, `branch_name` |
Expand All @@ -358,6 +416,7 @@ The exact fields vary by command. Common fields include:
| `poly format --json` | `success`, `check_only`, `format_errors`, `affected`, `ty_ran`, `ty_returncode`, `ty_timed_out` |
| `poly init --json` | `success`, `root_path` |
| `poly chat --json` | `conversations` (array); optional `push` (when `--push` is used) |
| `poly deployments list --json` | `versions`, `active_deployment_hashes` |

For `poly branch delete --json`, when a branch that was the current branch is deleted, the response also includes `"switched_to": "main"`.

Expand Down Expand Up @@ -429,7 +488,7 @@ A typical CLI workflow looks like this:
4. inspect changes with `poly status` and `poly diff`
5. validate with `poly validate`
6. push with `poly push`
7. optionally review with `poly review`
7. optionally review with `poly review create`
8. test or chat with the agent using `poly chat`

!!! info "Run commands from the project folder"
Expand Down
23 changes: 12 additions & 11 deletions docs/docs/tutorials/build-an-agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -193,7 +193,7 @@ Add or edit [knowledge-base topics](../reference/topics.md) used for retrieval.

#### Agent settings

Update the [personality, role, and rules](../reference/agent_settings.md) that define the agent’s global behavior.
Update the [personality, role, and rules](../reference/agent_settings.md) that define the agent's global behavior.

#### Flows

Expand Down Expand Up @@ -222,10 +222,10 @@ Inspect the local changes before pushing.
~~~bash
poly status
poly diff
poly diff <file>
poly diff --files <file>
poly validate
poly format
poly revert --all
poly revert
poly revert <file>
~~~

Expand Down Expand Up @@ -258,8 +258,8 @@ poly chat --environment sandbox --functions --flows
Review, refine, and test again. You can also use the review command to share diffs with teammates.

~~~bash
poly review
poly review --before main --after my-feature
poly review create
poly review create --before main --after my-feature
~~~

Make test calls, inspect transcripts, refine prompts, flows, and functions, and then re-push.
Expand Down Expand Up @@ -367,7 +367,7 @@ Provide the coding tool with the information you gathered earlier.
Include:

- project-specific requirements
- the URL to the business’s public API documentation
- the URL to the business's public API documentation
- relevant internal context
- useful patterns or best practices from previous projects

Expand Down Expand Up @@ -456,12 +456,13 @@ At that point, the agent is live.
| **poly pull** | Pull remote config into the local project |
| **poly push** | Push local changes to Agent Studio |
| **poly status** | List changed files |
| **poly diff** | Show diffs |
| **poly revert** | Revert local changes |
| **poly diff** | Show diffs (local vs remote, version hash, or `--before`/`--after`) |
| **poly revert** | Revert local changes (all by default, or specific files) |
| **poly branch** | Branch management |
| **poly format** | Format resource files |
| **poly format** | Format resource files (all or `--files` for specific files) |
| **poly validate** | Validate project configuration locally |
| **poly review** | Create a diff review page |
| **poly review** | Diff review page: `create`, `list`, `delete` |
| **poly deployments** | View deployment history (`list`, with `--env`, `--limit`, `--details`) |
| **poly chat** | Start an interactive session with the agent |
| **poly docs** | Output resource documentation |

Expand Down Expand Up @@ -492,4 +493,4 @@ At that point, the agent is live.

[Open the walkthrough video](../get-started/walkthrough-video.md)

</div>
</div>
Loading