npm package: @sstar/gerrit-cli
Description: CLI tool for Gerrit code review integration
Latest version: 1.1.5

# 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

```bash
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:
```bash
chmod 600 ~/.netrc
```

### 2. Gerrit URL

Set the `GERRIT_URL` environment variable:

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

Or use the `-u` option with each command:

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

## Usage

### Global Options

```bash
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

```bash
gerrit status <change-id>

# Example:
gerrit status 12345
gerrit status I1234567890abcdef

# JSON output:
gerrit --json status 12345
```

#### Get Comments

```bash
gerrit comments <change-id>

# Example:
gerrit comments 12345
```

#### Get Cherry-Pick URL

```bash
gerrit cherry-pick <change-id>

# Example:
gerrit cherry-pick 12345
```

#### Get Diff

```bash
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

```bash
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

```bash
gerrit topic <topic>

# Example:
gerrit topic feature-auth
```

### Write Commands

#### Submit Change

```bash
gerrit submit <change-id>

# Example:
gerrit submit 12345
```

#### Abandon Change

```bash
gerrit abandon <change-id> [options]

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

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

#### Restore Change

```bash
gerrit restore <change-id> [options]

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

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

#### Review Change

```bash
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

```bash
gerrit rebase <change-id>

# Example:
gerrit rebase 12345
```

#### Add Reviewer

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

# Example:
gerrit add-reviewer 12345 reviewer@example.com
gerrit add-reviewer 12345 john.doe
```

#### Delete Reviewer

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

# Example:
gerrit delete-reviewer 12345 reviewer@example.com
```

#### Set Topic

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

# Example:
gerrit set-topic 12345 feature-auth
```

#### Revert Change

```bash
gerrit revert <change-id> [options]

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

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

#### Set Private

```bash
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.

```bash
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.

```bash
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).

```bash
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.

```bash
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.

```bash
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.

```bash
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).

```bash
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

```bash
gerrit search "status:open owner:self"
```

#### Review and Submit a Change

```bash
# 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

```bash
# Add reviewers
gerrit add-reviewer 12345 reviewer1@example.com
gerrit add-reviewer 12345 reviewer2@example.com

# Set topic
gerrit set-topic 12345 feature-auth

# Rebase if needed
gerrit rebase 12345
```

#### Work with Topics

```bash
# 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:

```bash
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

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

Solution: Set the environment variable or use `-u` option:
```bash
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

```bash
# Run in development mode
npm run dev

# Build TypeScript
npm run build

# Run built version
npm start
```

## License

MIT