Gerrit CLI

A command-line interface tool for Gerrit code review integration.

Features

Read Operations

• Automatic authentication using ~/.netrc
• Retrieve review comments for changes
• Get change status and metadata
• Generate cherry-pick commands
• View diffs between patch sets
• Advanced search with full Gerrit query syntax

Write Operations

• Submit changes for merging
• Abandon or restore changes
• Add reviews with Code-Review/Verified votes
• Rebase changes onto target branch
• Manage reviewers (add/remove)
• Set/update change topics
• Revert submitted changes
• Mark changes as private/public
• Manage comments (post, reply, drafts, delete)

Installation

Prerequisites

• Node.js >= 18
• Gerrit instance with API access
• Credentials in ~/.netrc

Setup

npm install
npm run build
npm link  # Install globally as 'gerrit' command

Configuration

1. Gerrit Credentials

Configure ~/.netrc with your Gerrit credentials:

machine gerrit.example.com
login your-username
password your-api-token

Set proper permissions:

chmod 600 ~/.netrc

2. Gerrit URL

Set the GERRIT_URL environment variable:

export GERRIT_URL=https://gerrit.example.com

Or use the -u option with each command:

gerrit -u https://gerrit.example.com status 12345

Usage

Global Options

gerrit [options] <command>

Options:
  -V, --version        output version number
  -j, --json           Output as JSON
  -u, --url <url>      Gerrit URL (overrides GERRIT_URL env var)
  -h, --help           display help for command

Read Commands

Get Change Status

gerrit status <change-id>

# Example:
gerrit status 12345
gerrit status I1234567890abcdef

# JSON output:
gerrit --json status 12345

Get Comments

gerrit comments <change-id>

# Example:
gerrit comments 12345

Get Cherry-Pick URL

gerrit cherry-pick <change-id>

# Example:
gerrit cherry-pick 12345

Get Diff

gerrit diff <change-id> [options]

Options:
  -r, --revision <revision>  Revision ID (default: "current")
  -f, --file <file>          File path

# Example:
gerrit diff 12345
gerrit diff 12345 -r 2
gerrit diff 12345 -f src/main.ts

Search Changes

gerrit search <query>

# Examples:
gerrit search "status:open owner:self"
gerrit search "project:my-project branch:main"
gerrit search "is:open reviewer:self"

Query by Topic

gerrit topic <topic>

# Example:
gerrit topic feature-auth

Write Commands

Submit Change

gerrit submit <change-id>

# Example:
gerrit submit 12345

Abandon Change

gerrit abandon <change-id> [options]

Options:
  -m, --message <message>  Abandon message

# Example:
gerrit abandon 12345
gerrit abandon 12345 -m "No longer needed"

Restore Change

gerrit restore <change-id> [options]

Options:
  -m, --message <message>  Restore message

# Example:
gerrit restore 12345
gerrit restore 12345 -m "Actually still needed"

Review Change

gerrit review <change-id> [options]

Options:
  -m, --message <message>  Review message
  -l, --label <label>      Label (e.g., "Code-Review:2")

# Examples:
gerrit review 12345 -m "Looks good to me"
gerrit review 12345 -l "Code-Review:2"
gerrit review 12345 -m "LGTM" -l "Code-Review:2" -l "Verified:1"

Rebase Change

gerrit rebase <change-id>

# Example:
gerrit rebase 12345

Add Reviewer

gerrit add-reviewer <change-id> <reviewer>

# Example:
gerrit add-reviewer 12345 [email protected]
gerrit add-reviewer 12345 john.doe

Delete Reviewer

gerrit delete-reviewer <change-id> <reviewer>

# Example:
gerrit delete-reviewer 12345 [email protected]

Set Topic

gerrit set-topic <change-id> <topic>

# Example:
gerrit set-topic 12345 feature-auth

Revert Change

gerrit revert <change-id> [options]

Options:
  -m, --message <message>  Revert message

# Example:
gerrit revert 12345
gerrit revert 12345 -m "This broke production"

Set Private

gerrit private <change-id> [options]

Options:
  --unmark  Unmark as private

# Examples:
gerrit private 12345        # Mark as private
gerrit private 12345 --unmark  # Unmark as private

Comment Commands

The comment command provides subcommands for managing comments on changes.

Post Comment

Post an inline or file-level comment on a change.

gerrit comment post <change-id> [options]

Options:
  -p, --path <path>        File path (required)
  -l, --line <line>        Line number (omit for file-level comment)
  -m, --message <message>  Comment message (required)
  --unresolved             Mark comment as unresolved

# Examples:
# Post inline comment
gerrit comment post 12345 -p "src/main.ts" -l 10 -m "This needs refactoring"

# Post file-level comment
gerrit comment post 12345 -p "src/utils.ts" -m "Consider adding unit tests"

# Post unresolved comment
gerrit comment post 12345 -p "src/api.ts" -l 50 -m "Bug here" --unresolved

Reply to Comment

Reply to an existing comment.

gerrit comment reply <change-id> [options]

Options:
  -i, --in-reply-to <id>   ID of the comment to reply to (required)
  -m, --message <message>  Reply message (required)
  --resolved               Mark the comment thread as resolved
  --unresolved             Mark the comment thread as unresolved

# Examples:
gerrit comment reply 12345 -i abc123... -m "Fixed in patchset 2"
gerrit comment reply 12345 -i abc123... -m "Done" --resolved

Create Draft Comment

Create a draft comment (not published immediately).

gerrit comment draft <change-id> [options]

Options:
  -p, --path <path>        File path (required)
  -l, --line <line>        Line number (omit for file-level draft)
  -m, --message <message>  Draft message (required)

# Example:
gerrit comment draft 12345 -p "src/main.ts" -l 20 -m "TODO: optimize this"

List Drafts

List all draft comments on a change.

gerrit comment drafts <change-id> [options]

Options:
  -r, --revision <revision>  Revision ID (defaults to current)

# Example:
gerrit comment drafts 12345

Publish Drafts

Publish draft comments.

gerrit comment publish <change-id> [options]

Options:
  -d, --draft-id <id>       Draft ID (omit to publish all drafts)
  -r, --revision <revision>  Revision ID (defaults to current)

# Examples:
# Publish all drafts
gerrit comment publish 12345

# Publish specific draft
gerrit comment publish 12345 -d abc123...

Delete Draft

Delete a draft comment.

gerrit comment delete-draft <change-id> [options]

Options:
  -d, --draft-id <id>       Draft ID to delete (required)
  -r, --revision <revision>  Revision ID (defaults to current)

# Example:
gerrit comment delete-draft 12345 -d abc123...

Delete Comment

Delete a published comment (requires permissions).

gerrit comment delete <change-id> [options]

Options:
  -c, --comment-id <id>  Comment ID to delete (required)

# Example:
gerrit comment delete 12345 -c abc123...

Examples

Common Workflows

Check Your Open Changes

gerrit search "status:open owner:self"

Review and Submit a Change

# Review the change
gerrit status 12345
gerrit diff 12345
gerrit comments 12345

# Add review
gerrit review 12345 -m "LGTM" -l "Code-Review:2"

# Submit
gerrit submit 12345

Manage a Change

# Add reviewers
gerrit add-reviewer 12345 [email protected]
gerrit add-reviewer 12345 [email protected]

# Set topic
gerrit set-topic 12345 feature-auth

# Rebase if needed
gerrit rebase 12345

Work with Topics

# Find all changes in a topic
gerrit topic feature-auth

# Review all changes in a topic
gerrit topic feature-auth --json | jq -r '.[].change_id' | xargs -I {} gerrit review {} -l "Code-Review:2"

Output Formats

Default Output

Human-readable format with tables and colors.

JSON Output

Use --json flag for machine-readable output:

gerrit --json status 12345
gerrit --json search "status:open"

Troubleshooting

Authentication Failed

• Ensure ~/.netrc exists and has correct permissions (chmod 600 ~/.netrc)
• Verify credentials match your Gerrit instance
• Check that the machine name in .netrc matches the hostname (without https://)

GERRIT_URL Not Set

Error: GERRIT_URL is required. Set it via -u option or GERRIT_URL environment variable.

Solution: Set the environment variable or use -u option:

export GERRIT_URL=https://gerrit.example.com
# or
gerrit -u https://gerrit.example.com status 12345

Connection Error

• Verify Gerrit URL is accessible
• Check network/firewall settings
• Ensure Gerrit API is enabled

Change Not Found

• Verify the change ID exists in Gerrit
• Try using numeric ID instead of Change-Id
• Check you have permission to view the change

Architecture

src/
├── cli.ts               # CLI entry point with commander
├── cli-comment.ts       # Comment subcommands router
├── config/              # Configuration management
│   ├── auth.ts         # .netrc parsing
│   └── gerrit-config.ts # URL configuration
├── lib/                # Shared libraries
│   └── gerrit-client.ts # HTTP client with XSSI handling
├── tools/              # Tool implementations (reused from MCP)
│   ├── get-comments.ts
│   ├── get-status.ts
│   ├── get-cherrypick-url.ts
│   ├── get-diff.ts
│   ├── search-changes.ts
│   ├── post-comment.ts
│   ├── reply-comment.ts
│   ├── create-draft.ts
│   ├── list-drafts.ts
│   ├── publish-drafts.ts
│   ├── delete-draft.ts
│   └── delete-comment.ts
└── utils/              # CLI utilities
    └── output.ts       # Output formatting

Development

# Run in development mode
npm run dev

# Build TypeScript
npm run build

# Run built version
npm start

License

MIT