@aaronshaf/ger 4.0.0 → 4.0.1

package/skills/gerrit-workflow/reference.md

@@ -2,6 +2,17 @@
 
 Complete reference documentation for all ger CLI commands.
 
+## Output Format Flags
+
+All commands that produce output support:
+- `--json` — Structured JSON for programmatic consumption
+- `--xml` — XML with CDATA-wrapped content (preferred for LLM consumption)
+- (default) — Colored terminal output
+
+`--json` and `--xml` are mutually exclusive.
+
+---
+
 ## Change Viewing Commands
 
 ### show
@@ -14,31 +25,22 @@ ger show [change-id] [options]
 ```
 
 **Options:**
-- `--format <format>` - Output format: `text`, `json`, `markdown`
-- `--no-comments` - Exclude comments from output
-- `--no-diff` - Exclude diff from output
+- `--json` — JSON output
+- `--xml` — XML output
+- `--no-comments` — Exclude comments
+- `--no-diff` — Exclude diff
 
 **Examples:**
 ```bash
-# Show current change
 ger show
-
-# Show specific change
 ger show 12345
-
-# Show as JSON
-ger show 12345 --format json
-
-# Show without comments
+ger show 12345 --xml
 ger show --no-comments
 ```
 
-**Output includes:**
-- Change metadata (owner, status, subject)
-- Commit message
-- File diffs
-- All comments and inline feedback
-- Jenkins build status (if available)
+**Output includes:** metadata, commit message, file diffs, all comments, Jenkins build status
+
+---
 
 ### diff
 
@@ -50,22 +52,20 @@ ger diff [change-id] [options]
 ```
 
 **Options:**
-- `--format <format>` - Output format: `unified`, `context`, `json`
-- `--file <path>` - Show diff for specific file only
-- `--base <revision>` - Compare against specific base revision
+- `--file <path>` — Show diff for specific file only
+- `--base <revision>` — Compare against specific base revision
+- `--json` — JSON output
+- `--xml` — XML output
 
 **Examples:**
 ```bash
-# Get unified diff
 ger diff 12345
-
-# Get diff for specific file
 ger diff 12345 --file src/api/client.ts
-
-# Get diff as JSON
-ger diff 12345 --format json
+ger diff 12345 --xml
 ```
 
+---
+
 ### comments
 
 View all comments on a change.
@@ -76,320 +76,389 @@ ger comments [change-id] [options]
 ```
 
 **Options:**
-- `--format <format>` - Output format: `text`, `json`, `markdown`
-- `--unresolved-only` - Show only unresolved comments
-- `--file <path>` - Show comments for specific file only
+- `--unresolved-only` — Show only unresolved comments
+- `--file <path>` — Show comments for specific file only
+- `--json` — JSON output
+- `--xml` — XML output
 
-**Examples:**
-```bash
-# View all comments
-ger comments 12345
+---
+
+### files
 
-# View unresolved comments only
-ger comments 12345 --unresolved-only
+List changed files in a change.
 
-# View comments for specific file
-ger comments 12345 --file src/api/client.ts
+**Syntax:**
+```bash
+ger files [change-id] [options]
 ```
 
-## Change Management Commands
+**Options:**
+- `--json` — JSON output
+- `--xml` — XML output
 
-### mine
+---
+
+### reviewers
 
-List all changes owned by you.
+List reviewers on a change.
 
 **Syntax:**
 ```bash
-ger mine [options]
+ger reviewers [change-id] [options]
 ```
 
 **Options:**
-- `--status <status>` - Filter by status: `open`, `merged`, `abandoned`
-- `--format <format>` - Output format: `table`, `json`, `list`
-- `--limit <n>` - Limit number of results
+- `--json` — JSON output
+- `--xml` — XML output
 
-**Examples:**
+---
+
+## Change Listing Commands
+
+### list
+
+List your changes or changes needing your review.
+
+**Syntax:**
 ```bash
-# List all your open changes
-ger mine
+ger list [options]
+```
 
-# List merged changes
-ger mine --status merged
+**Options:**
+- `--status <status>` — Filter by status: `open`, `merged`, `abandoned` (default: open)
+- `-n, --limit <n>` — Maximum number of changes (default: 25)
+- `--detailed` — Show detailed information
+- `--reviewer` — Show changes where you are a reviewer or CC'd
+- `--json` — JSON output
+- `--xml` — XML output
+
+---
 
-# List as JSON
-ger mine --format json
+### mine
+
+List all changes owned by you. Alias for `ger list`.
+
+**Syntax:**
+```bash
+ger mine [options]
 ```
 
-### incoming
+**Options:**
+- `--json` — JSON output
+- `--xml` — XML output
+
+---
+
+### incoming / team
 
-List changes that need your review.
+List changes where you are a reviewer or CC'd.
+Both commands are aliases for `ger list --reviewer`.
+Query: `(reviewer:self OR cc:self) status:open`
 
 **Syntax:**
 ```bash
 ger incoming [options]
+ger team [options]
 ```
 
 **Options:**
-- `--format <format>` - Output format: `table`, `json`, `list`
-- `--limit <n>` - Limit number of results
+- `--status <status>` — Filter by status (default: open)
+- `-n, --limit <n>` — Maximum number of changes (default: 25)
+- `--detailed` — Show detailed information
+- `--all-verified` — Include all verification states (default: excludes unverified)
+- `-f, --filter <query>` — Append custom Gerrit query syntax (e.g. `project:canvas-lms`)
+- `--json` — JSON output
+- `--xml` — XML output
 
 **Examples:**
 ```bash
-# List incoming review requests
-ger incoming
-
-# Get as JSON
-ger incoming --format json
+ger team
+ger incoming --filter "project:canvas-lms"
+ger team --all-verified --json
 ```
 
-### open
+---
+
+### search
 
-List all open changes in the project.
+Search for changes using Gerrit query syntax.
 
 **Syntax:**
 ```bash
-ger open [options]
+ger search [query] [options]
 ```
 
 **Options:**
-- `--owner <email>` - Filter by change owner
-- `--format <format>` - Output format: `table`, `json`, `list`
-- `--limit <n>` - Limit number of results
+- `-n, --limit <n>` — Maximum results (default: 25)
+- `--xml` — XML output
+
+**Common Query Operators:**
+- `owner:USER` / `owner:self`
+- `status:open|merged|abandoned`
+- `project:NAME`
+- `branch:NAME`
+- `reviewer:USER` / `cc:USER`
+- `is:wip` / `is:submittable`
+- `after:YYYY-MM-DD` / `before:YYYY-MM-DD`
+- `age:1d|2w|1mon`
+- `label:Code-Review+2`
 
 **Examples:**
 ```bash
-# List all open changes
-ger open
-
-# Filter by owner
-ger open --owner user@example.com
+ger search "owner:self status:open"
+ger search "is:wip"
+ger search "project:canvas-lms after:2025-01-01" -n 10 --xml
 ```
 
-### abandon
+---
 
-Mark a change as abandoned.
+## Comment and Vote Commands
+
+### comment
+
+Post a comment on a Gerrit change.
 
 **Syntax:**
 ```bash
-ger abandon [change-id] [options]
+ger comment [change-id] [options]
 ```
 
 **Options:**
-- `--message <text>` - Abandonment message
+- `-m, --message <text>` — Comment message (reads from stdin if omitted)
+- `--file <path>` — File for inline comment
+- `--line <n>` — Line number for inline comment
+- `--unresolved` — Mark comment as unresolved
 
 **Examples:**
 ```bash
-# Abandon with message
-ger abandon 12345 --message "No longer needed"
-
-# Abandon current change
-ger abandon
+ger comment 12345 -m "Looks good!"
+ger comment 12345 --file src/api/client.ts --line 42 -m "Consider error handling"
+echo "Review feedback" | ger comment 12345
 ```
 
-### checkout
+---
 
-Checkout a specific change revision locally.
+### vote
+
+Vote on a Gerrit change.
 
 **Syntax:**
 ```bash
-ger checkout <change-id> [options]
+ger vote [change-id] <label> <score>
 ```
 
-**Options:**
-- `--revision <n>` - Checkout specific patchset revision (default: latest)
-
 **Examples:**
 ```bash
-# Checkout latest revision
-ger checkout 12345
-
-# Checkout specific revision
-ger checkout 12345 --revision 3
+ger vote 12345 Code-Review +2
+ger vote 12345 Code-Review -1
+ger vote 12345 Verified +1
+ger vote --xml
 ```
 
-### push
+---
 
-Push changes to Gerrit for review.
+## Change Management Commands
+
+### abandon
+
+Mark a change as abandoned.
 
 **Syntax:**
 ```bash
-ger push [options]
+ger abandon [change-id] [options]
 ```
 
 **Options:**
-- `-b, --branch <branch>` - Target branch (auto-detected from tracking branch)
-- `-t, --topic <topic>` - Topic name
-- `-r, --reviewer <email>` - Add reviewer (can be repeated)
-- `--cc <email>` - Add CC (can be repeated)
-- `--wip` - Mark as work-in-progress (not ready for review)
-- `--ready` - Mark as ready for review (remove WIP status)
-- `--hashtag <tag>` - Add hashtag (can be repeated)
-- `--private` - Mark as private change
-- `--draft` - Alias for --wip
-- `--dry-run` - Preview push without actually pushing
+- `-m, --message <text>` — Abandonment message
+- `--json` — JSON output
+- `--xml` — XML output
 
-**Examples:**
+---
+
+### restore
+
+Restore an abandoned change.
+
+**Syntax:**
 ```bash
-# Basic push to auto-detected branch
-ger push
+ger restore [change-id] [options]
+```
 
-# Push to specific branch
-ger push -b main
-ger push --branch feature/auth
+**Options:**
+- `-m, --message <text>` — Restoration message
+- `--json` — JSON output
+- `--xml` — XML output
 
-# Push with topic
-ger push -t my-feature
+---
 
-# Push with reviewers
-ger push -r alice@example.com -r bob@example.com
+### submit
 
-# Push with CC
-ger push --cc manager@example.com
+Submit a change (merge it).
 
-# Push as work-in-progress (WIP)
-ger push --wip
+**Syntax:**
+```bash
+ger submit [change-id] [options]
+```
 
-# Mark change as ready for review
-ger push --ready
+**Options:**
+- `--json` — JSON output
+- `--xml` — XML output
 
-# Add hashtag
-ger push --hashtag bugfix
+---
 
-# Combine multiple options
-ger push -b main -t refactor-auth -r alice@example.com --wip
+### set-wip
 
-# Preview push without executing
-ger push --dry-run
-```
+Mark a change as work-in-progress.
 
-**WIP Workflow:**
-Work-in-progress changes are useful for getting early feedback or saving work:
+**Syntax:**
 ```bash
-# Push initial work as WIP
-ger push --wip
+ger set-wip [change-id] [options]
+```
+
+**Options:**
+- `-m, --message <text>` — Optional message
+- `--json` — JSON output
+- `--xml` — XML output
+
+---
 
-# Continue updating (stays WIP)
-ger push --wip
+### set-ready
 
-# Mark ready when complete
-ger push --ready
+Mark a change as ready for review.
+
+**Syntax:**
+```bash
+ger set-ready [change-id] [options]
 ```
 
-**Features:**
-- Auto-installs commit-msg hook if missing
-- Auto-detects target branch from tracking branch or defaults to main/master
-- Validates reviewer email addresses
-- Returns change URL on successful push
+**Options:**
+- `-m, --message <text>` — Optional message
+- `--json` — JSON output
+- `--xml` — XML output
+
+---
 
-### search
+### topic
 
-Search for changes using Gerrit query syntax.
+Get or set the topic on a change.
 
 **Syntax:**
 ```bash
-ger search [query] [options]
+ger topic [change-id] [topic] [options]
 ```
 
 **Options:**
-- `-n, --limit <n>` - Maximum number of results (default: 25)
-- `--format <format>` - Output format: `table`, `json`, `list`
-- `--xml` - XML output for automation
-
-**Common Query Operators:**
-- `owner:USER` - Changes owned by USER (use 'self' for yourself)
-- `status:STATE` - open, merged, abandoned, closed
-- `project:NAME` - Changes in a specific project
-- `branch:NAME` - Changes targeting a branch
-- `age:TIME` - Time since last update (e.g., 1d, 2w, 1mon)
-- `before:DATE` - Changes modified before date (YYYY-MM-DD)
-- `after:DATE` - Changes modified after date (YYYY-MM-DD)
-- `is:wip` - Work-in-progress changes
-- `is:submittable` - Changes ready to submit
-- `reviewer:USER` - Changes where USER is a reviewer
-- `label:NAME=VALUE` - Filter by label (e.g., label:Code-Review+2)
+- `--delete` — Remove the topic
+- `--json` — JSON output
+- `--xml` — XML output
 
 **Examples:**
 ```bash
-# Search for all open changes (default)
-ger search
+ger topic 12345              # get topic
+ger topic 12345 my-feature   # set topic
+ger topic 12345 --delete     # delete topic
+```
 
-# Search for your open changes
-ger search "owner:self status:open"
+---
 
-# Search for changes by a specific user
-ger search "owner:john@example.com"
+## Push and Checkout Commands
 
-# Search by project
-ger search "project:my-project status:open"
+### push
 
-# Search with date filters
-ger search "owner:self after:2025-01-01"
-ger search "status:merged age:7d"
+Push changes to Gerrit for review.
 
-# Search for WIP changes
-ger search "is:wip"
-ger search "owner:self is:wip"
+**Syntax:**
+```bash
+ger push [options]
+```
 
-# Search for submittable changes
-ger search "is:submittable"
+**Options:**
+- `-b, --branch <branch>` — Target branch (auto-detected from tracking branch)
+- `-t, --topic <topic>` — Topic name
+- `-r, --reviewer <email>` — Add reviewer (repeatable)
+- `--cc <email>` — Add CC (repeatable)
+- `--wip` — Mark as work-in-progress
+- `--ready` — Mark as ready for review
+- `--hashtag <tag>` — Add hashtag (repeatable)
+- `--private` — Mark as private
+- `--dry-run` — Preview without pushing
+
+---
 
-# Combine filters
-ger search "owner:self status:merged before:2025-06-01"
+### checkout
 
-# Limit results
-ger search "project:my-project" -n 10
+Checkout a specific change revision locally.
 
-# XML output for automation
-ger search "owner:self" --xml
+**Syntax:**
+```bash
+ger checkout <change-id> [options]
 ```
 
-## Commenting Commands
+**Options:**
+- `--revision <n>` — Checkout specific patchset (default: latest)
 
-### comment
+---
 
-Post a comment on a Gerrit change.
+### cherry
+
+Cherry-pick a Gerrit change into the current branch.
 
 **Syntax:**
 ```bash
-ger comment [change-id] [options]
+ger cherry <change-id>[/<patchset>] [options]
 ```
 
 **Options:**
-- `-m, --message <text>` - Comment message
-- `--file <path>` - File for inline comment
-- `--line <n>` - Line number for inline comment
-- `--unresolved` - Mark comment as unresolved (requiring action)
+- `--no-commit` — Stage changes without committing (`git cherry-pick -n`)
+- `--no-verify` — Skip pre-commit hooks during cherry-pick
+- `--remote <name>` — Use specific git remote (default: auto-detected from Gerrit host)
+
+**Input formats:**
+- `12345` — Latest patchset
+- `12345/3` — Specific patchset
+- `If5a3ae8cb5a107e187447802358417f311d0c4b1` — Change-ID
+- `https://gerrit.example.com/c/my-project/+/12345` — Full URL
 
 **Examples:**
 ```bash
-# Post general comment
-ger comment 12345 -m "Looks good!"
+ger cherry 12345
+ger cherry 12345/3
+ger cherry 12345 --no-commit
+ger cherry 12345 --no-verify
+```
 
-# Post inline comment
-ger comment 12345 --file src/api/client.ts --line 42 -m "Consider error handling here"
+---
 
-# Mark as unresolved
-ger comment 12345 -m "Please fix the type error" --unresolved
+### rebase
 
-# Pipe input from stdin
-echo "Review feedback from AI" | ger comment 12345
-```
+Rebase a change on Gerrit (server-side rebase).
 
-**Piped Input:**
-The comment command accepts piped input, making it easy to integrate with AI tools:
+**Syntax:**
 ```bash
-# AI-generated review
-cat diff.txt | ai-review-tool | ger comment 12345
+ger rebase [change-id] [options]
+```
+
+**Options:**
+- `--base <sha-or-id>` — Rebase onto specific base commit or change
+- `--allow-conflicts` — Allow rebase even when conflicts exist
+- `--json` — JSON output
+- `--xml` — XML output
 
-# GPT-4 review
-ger diff 12345 | gpt-4-review | ger comment 12345
+**Examples:**
+```bash
+ger rebase
+ger rebase 12345
+ger rebase 12345 --allow-conflicts
+ger rebase 12345 --base abc123def --xml
 ```
 
-## Build Integration Commands
+---
+
+## Build and CI Commands
 
 ### build-status
 
-Check the build status for a change.
+Check the Jenkins build status for a change.
 
 **Syntax:**
 ```bash
@@ -397,332 +466,325 @@ ger build-status [change-id] [options]
 ```
 
 **Options:**
-- `--watch` - Watch build status and wait for completion
-- `--interval <seconds>` - Polling interval for watch mode (default: 30)
-- `--timeout <seconds>` - Maximum wait time for watch mode
+- `--watch` — Poll until build completes
+- `--interval <seconds>` — Polling interval (default: 30)
+- `--timeout <seconds>` — Maximum wait time
+- `--exit-status` — Return non-zero exit code on build failure (for scripting)
+- `--json` — JSON output
+- `--xml` — XML output
 
 **Examples:**
 ```bash
-# Check current status
 ger build-status 12345
-
-# Watch until build completes
-ger build-status 12345 --watch
-
-# Watch with custom interval and timeout
-ger build-status 12345 --watch --interval 20 --timeout 1800
+ger build-status --watch --interval 20 --timeout 1800
+ger build-status --exit-status
 ```
 
+---
+
 ### extract-url
 
-Extract URLs from change metadata (e.g., build reports, Jenkins links).
+Extract URLs from change messages (e.g., Jenkins build links).
 
 **Syntax:**
 ```bash
-ger extract-url <url-type> [change-id]
+ger extract-url <pattern> [change-id]
 ```
 
-**URL Types:**
-- `build-summary-report` - Jenkins build summary report
-- `jenkins` - Main Jenkins build URL
-- `test-results` - Test results URL
-
 **Examples:**
 ```bash
-# Extract build summary report URL
 ger extract-url "build-summary-report"
-
-# Extract for specific change
-ger extract-url "jenkins" 12345
-
-# Get the latest URL
 ger extract-url "build-summary-report" | tail -1
+ger extract-url "jenkins" 12345
 ```
 
-## Configuration Commands
+---
 
-### config
+### retrigger
 
-Manage ger CLI configuration.
+Post a CI retrigger comment on a change.
 
 **Syntax:**
 ```bash
-ger config <action> [key] [value]
+ger retrigger [change-id] [options]
 ```
 
-**Actions:**
-- `get <key>` - Get configuration value
-- `set <key> <value>` - Set configuration value
-- `list` - List all configuration
-- `reset` - Reset to defaults
+**Options:**
+- `--json` — JSON output
+- `--xml` — XML output
+
+The retrigger comment is configured via `ger setup` or prompted on first use and saved to config.
 
 **Examples:**
 ```bash
-# Set Gerrit URL
-ger config set gerrit.url https://gerrit.example.com
-
-# Get current URL
-ger config get gerrit.url
-
-# List all config
-ger config list
+ger retrigger
+ger retrigger 12345
+ger retrigger 12345 --json
 ```
 
-## Groups and Reviewers Commands
+---
 
-### add-reviewer
+## Analytics Commands
 
-Add reviewers, groups, or CCs to a change.
+### analyze
+
+View merged change analytics.
 
 **Syntax:**
 ```bash
-ger add-reviewer <reviewers...> -c <change-id> [options]
+ger analyze [options]
 ```
 
 **Options:**
-- `-c, --change <id>` - Change ID (required)
-- `--group` - Add as group instead of individual reviewer
-- `--cc` - Add as CC instead of reviewer
-- `--notify <level>` - Notification level: `none`, `owner`, `owner_reviewers`, `all`
-- `--xml` - XML output for automation
+- `--start-date <YYYY-MM-DD>` — Start date (default: January 1 of current year)
+- `--end-date <YYYY-MM-DD>` — End date (default: today)
+- `--repo <name>` — Filter by repository
+- `--json` — JSON output
+- `--xml` — XML output
+- `--markdown` — Markdown output
+- `--csv` — CSV output
+- `--output <file>` — Write output to file
 
 **Examples:**
 ```bash
-# Add individual reviewers
-ger add-reviewer user@example.com -c 12345
-ger add-reviewer user1@example.com user2@example.com -c 12345
+ger analyze
+ger analyze --start-date 2025-01-01 --end-date 2025-06-30
+ger analyze --repo canvas-lms --markdown
+ger analyze --csv --output report.csv
+```
 
-# Add a group as reviewer
-ger add-reviewer --group project-reviewers -c 12345
+---
 
-# Add a group as CC
-ger add-reviewer --group administrators --cc -c 12345
+### update
 
-# Add as CC instead of reviewer
-ger add-reviewer --cc user@example.com -c 12345
+Update local cache of merged changes.
 
-# Suppress notifications
-ger add-reviewer --notify none user@example.com -c 12345
+**Syntax:**
+```bash
+ger update [options]
+```
 
-# XML output
-ger add-reviewer user@example.com -c 12345 --xml
+**Options:**
+- `--since <YYYY-MM-DD>` — Fetch changes since this date
+- `--json` — JSON output
+
+---
+
+### failures
+
+View recent build failures summary.
+
+**Syntax:**
+```bash
+ger failures [options]
 ```
 
-### groups
+**Options:**
+- `--json` — JSON output
+- `--xml` — XML output
 
-List and search Gerrit groups.
+---
+
+## Worktree (tree) Commands
+
+### tree setup
+
+Create a git worktree for a Gerrit change, checked out at `<repo-root>/.ger/<change-number>/`.
 
 **Syntax:**
 ```bash
-ger groups [options]
+ger tree setup <change-id>[:<patchset>] [options]
 ```
 
 **Options:**
-- `--pattern <regex>` - Filter groups by name pattern
-- `--owned` - Show only groups you own
-- `--project <name>` - Show groups for a specific project
-- `--user <account>` - Show groups a user belongs to
-- `--limit <n>` - Limit results (default: 25)
-- `--xml` - XML output for automation
+- `--json` — JSON output
+- `--xml` — XML output
 
 **Examples:**
 ```bash
-# List all groups
-ger groups
-
-# Filter by pattern
-ger groups --pattern "^project-.*"
+ger tree setup 12345
+ger tree setup 12345:3      # specific patchset
+ger tree setup 12345 --xml
+```
 
-# Show only owned groups
-ger groups --owned
+---
 
-# Show groups for a project
-ger groups --project my-project
+### trees
 
-# Limit results
-ger groups --limit 50
+List all ger-managed worktrees.
 
-# XML output
-ger groups --xml
+**Syntax:**
+```bash
+ger trees [options]
 ```
 
-**Output includes:**
-- Group name and ID
-- Description
-- Owner group
-- Visibility settings
-- Creation date (when available)
+**Options:**
+- `--json` — JSON output
+- `--xml` — XML output
 
-### groups-show
+---
 
-Show detailed information about a specific group.
+### tree rebase
+
+Rebase the current worktree onto the latest base branch. Must be run from inside a ger worktree.
 
 **Syntax:**
 ```bash
-ger groups-show <group-id> [options]
+ger tree rebase [options]
 ```
 
 **Options:**
-- `--xml` - XML output for automation
-
-**Group ID formats:**
-- Group name: `administrators`
-- Numeric ID: `1`
-- UUID: `uuid-123456`
+- `--onto <branch>` — Rebase onto specific branch (default: auto-detected from tracking branch)
+- `-i, --interactive` — Interactive rebase (`git rebase -i`)
+- `--json` — JSON output
+- `--xml` — XML output
 
 **Examples:**
 ```bash
-# Show by name
-ger groups-show administrators
+cd .ger/12345
+ger tree rebase
+ger tree rebase --onto origin/main
+ger tree rebase --interactive
+```
 
-# Show by numeric ID
-ger groups-show 1
+---
 
-# Show by UUID
-ger groups-show uuid-123456
+### tree cleanup
 
-# XML output
-ger groups-show administrators --xml
+Remove a ger-managed worktree.
+
+**Syntax:**
+```bash
+ger tree cleanup <change-id> [options]
 ```
 
-**Output includes:**
-- Basic group information (name, ID, owner, description)
-- Visibility settings
-- All group members with details
-- Subgroups (included groups)
-- Metadata (creation date, group ID)
+---
 
-### groups-members
+## Groups and Reviewer Commands
 
-List all members of a group.
+### add-reviewer
+
+Add reviewers, groups, or CCs to a change.
 
 **Syntax:**
 ```bash
-ger groups-members <group-id> [options]
+ger add-reviewer <reviewers...> -c <change-id> [options]
 ```
 
 **Options:**
-- `--xml` - XML output for automation
+- `-c, --change <id>` — Change ID (required)
+- `--group` — Add as group
+- `--cc` — Add as CC
+- `--notify <level>` — `none`, `owner`, `owner_reviewers`, `all`
+- `--xml` — XML output
 
-**Examples:**
-```bash
-# List members
-ger groups-members project-reviewers
+---
 
-# List members by numeric ID
-ger groups-members 1
+### remove-reviewer
 
-# XML output
-ger groups-members project-reviewers --xml
-```
+Remove a reviewer from a change.
 
-**Output includes:**
-- Member name
-- Email address
-- Username
-- Account ID
+**Syntax:**
+```bash
+ger remove-reviewer <account> -c <change-id> [options]
+```
 
-**Notes:**
-- All group commands are read-only
-- Group operations do not support creating, modifying, or deleting groups
-- Use with `add-reviewer --group` to add teams as reviewers
+**Options:**
+- `-c, --change <id>` — Change ID (required)
+- `--notify <level>` — `none`, `owner`, `owner_reviewers`, `all`
+- `--xml` — XML output
 
-## Global Options
+---
 
-These options work with all commands:
+### groups
 
-- `--help` - Show help for command
-- `--version` - Show ger version
-- `--no-cache` - Skip cache and fetch fresh data
-- `--debug` - Enable debug logging
-- `--quiet` - Suppress non-essential output
+List and search Gerrit groups.
 
-**Examples:**
+**Syntax:**
 ```bash
-# Show help for a command
-ger show --help
+ger groups [options]
+```
+
+**Options:**
+- `--pattern <regex>` — Filter by name pattern
+- `--owned` — Show only groups you own
+- `--project <name>` — Show groups for a project
+- `--user <account>` — Show groups a user belongs to
+- `--limit <n>` — Limit results (default: 25)
+- `--xml` — XML output
+
+---
+
+### groups-show
 
-# Skip cache
-ger mine --no-cache
+Show detailed information about a specific group.
 
-# Enable debug mode
-ger show 12345 --debug
+**Syntax:**
+```bash
+ger groups-show <group-id> [options]
 ```
 
-## Exit Codes
+**Options:**
+- `--xml` — XML output
 
-- `0` - Success
-- `1` - General error
-- `2` - Invalid arguments
-- `3` - API error
-- `4` - Authentication error
-- `5` - Not found error
+---
 
-## Environment Variables
+### groups-members
 
-- `GER_URL` - Gerrit server URL
-- `GER_USERNAME` - Gerrit username
-- `GER_PASSWORD` - Gerrit password/token
-- `GER_CACHE_DIR` - Cache directory path (default: `~/.ger/cache`)
-- `GER_LOG_LEVEL` - Log level: `debug`, `info`, `warn`, `error`
+List all members of a group.
 
-**Example:**
+**Syntax:**
 ```bash
-export GER_URL=https://gerrit.example.com
-export GER_LOG_LEVEL=debug
-ger mine
+ger groups-members <group-id> [options]
 ```
 
-## Cache Behavior
+**Options:**
+- `--xml` — XML output
 
-The ger CLI uses SQLite for local-first caching:
+---
 
-- **Changes** - Cached for 5 minutes
-- **Comments** - Cached for 2 minutes
-- **Diffs** - Cached for 10 minutes
-- **User data** - Cached for 1 hour
+## Configuration Commands
 
-Use `--no-cache` to bypass cache and fetch fresh data.
+### setup
 
-## API Rate Limiting
+Interactive first-time setup.
 
-The ger CLI respects Gerrit API rate limits:
+```bash
+ger setup
+```
 
-- Maximum 100 requests per minute
-- Automatic retry with exponential backoff
-- Rate limit status shown in debug mode
+Configures Gerrit URL, credentials, and retrigger comment.
 
-## Error Handling
+### config
 
-All commands use Effect Schema for validation and provide clear error messages:
+Manage ger CLI configuration.
 
+**Syntax:**
 ```bash
-# Invalid change ID
-$ ger show invalid
-Error: Invalid change ID format. Expected number or Change-Id string.
+ger config <action> [key] [value]
+```
 
-# Network error
-$ ger mine
-Error: Failed to connect to Gerrit server. Check your network connection.
+**Actions:** `get`, `set`, `list`, `reset`
 
-# Permission error
-$ ger abandon 12345
-Error: Permission denied. You must be the change owner to abandon it.
+**Examples:**
+```bash
+ger config list
+ger config get gerrit.url
+ger config set gerrit.url https://gerrit.example.com
 ```
 
-## Internationalization
+---
 
-The ger CLI supports multiple languages via i18next. Set your locale:
+## Auto-Detection
 
-```bash
-export LANG=es_ES.UTF-8
-ger mine
-```
+These commands auto-detect the change from the HEAD commit's `Change-Id` footer when no change-id is provided:
+
+`show`, `build-status`, `topic`, `rebase`, `extract-url`, `diff`, `comments`, `vote`, `retrigger`, `files`, `reviewers`
+
+---
+
+## Exit Codes
 
-Supported languages:
-- English (en)
-- Spanish (es)
-- French (fr)
-- German (de)
-- Japanese (ja)
-- Chinese (zh)
+- `0` — Success
+- `1` — General error (network, API, validation)
+- `build-status --exit-status` returns non-zero on build failure