prch - Pretty PR Checks

prch is a command-line tool that shows GitHub pull request (PR) checks in a clean, color-coded terminal view.

It is made for PR review workflows that use Terraform Cloud (TFC) and GitHub Actions. It hides routine checks and shows only the checks that need your attention.

Features

• List all open PRs in the current repo with their CI status, then pick one to view.
• Show the PR state (Draft, Open, Merged, Closed), review status, and comment count.
• Hide noise. Show only Terraform plans, failed checks, and pending checks.
• Show Terraform plans in a compact format (add / change / destroy counts).
• Watch mode: refresh every 10 seconds until all checks complete.
• Interactive mode: pick Terraform Cloud runs and see each changed resource and attribute.
• JSON output of the selected runs, to stdout or to a file.
• Clickable links in terminals that support OSC 8 hyperlinks.

Prerequisites

• Go 1.22 or later, to build the tool.
• A GitHub token. prch looks for it in this order:
  1. The GITHUB_TOKEN environment variable.
  2. The GH_TOKEN environment variable.
  3. The GitHub CLI (gh), through gh auth token.
• For interactive mode only: a Terraform Cloud token in ~/.terraform.d/credentials.tfrc.json. To create this file, run terraform login.

Installation

1. Build the binary and copy it to /usr/local/bin:

   make install
   

2. Make sure the install worked:

   prch --version
   

ℹ️ To build only, without install, run make build. To remove the local binary, run make clean.

Usage

Run prch from inside a local clone of a GitHub repo. prch reads the repo owner and name from the origin remote.

List open PRs

prch

prch shows all open PRs with their draft state and CI status. Use the arrow keys (or j / k) to select a PR. Press Enter to open it. Press q to quit.

View one PR

prch <PR_NUMBER>

Example:

prch 5

Watch mode

prch <PR_NUMBER> --watch
# or
prch <PR_NUMBER> -w

Watch mode:

• Refreshes every 10 seconds.
• Shows a "Last updated" timestamp.
• Stops when all checks complete.
• Stops when you press Ctrl+C.

Interactive mode

prch <PR_NUMBER> --interactive
# or
prch <PR_NUMBER> -i

After the checks table, prch shows a list of the Terraform Cloud runs. To use the list:

1. Press Space to select a run.
2. Press Enter to confirm.
3. Press q or Esc to cancel.

For each selected run, prch shows:

• The run ID, workspace name, status, and timestamp.
• The plan summary.
• Each resource to import, add, change, destroy, or replace.
• Each changed attribute, with its old value and new value.

ℹ️ If you use -w and -i together, the picker opens after watch mode ends or after you press Ctrl+C.

JSON output

# Print the selected runs as JSON
prch <PR_NUMBER> -i --json

# Write the selected runs to a file
prch <PR_NUMBER> -i --json plan.json

⚠️ --json works only together with -i.

All options

Option	Description
-w, --watch	Refresh every 10 seconds until all checks complete.
-i, --interactive	After the display, pick Terraform Cloud runs to expand.
--json [FILE]	With -i, output the selected runs as JSON. Write to FILE if given, else to stdout.
--version	Print the version and exit.
-h, --help	Show help and exit.

Output format

The PR view shows:

1. Header: the PR number, title, and URL in a box.
2. Status line: the PR state, review status, and comment count.
3. Check statistics: total checks, successes (with the hidden count), failures, and pending checks.
4. Check table: the filtered checks, with these columns:
   • Status icon: success, failure, or pending.
   • Check name. Terraform Cloud check names are shortened to TF - <workspace>.
   • Description. Terraform plans show as add / change / destroy counts. Other descriptions longer than 50 characters are cut.
   • URL to the check details.

Filter rules

prch shows these checks:

• ✅ Terraform plans
• ✅ Failed checks
• ✅ Pending or in-progress checks

prch hides these checks:

• ❌ Successful routine checks
• ❌ "Run not triggered" entries

If no checks remain after the filter, prch shows "All checks passed".

Example output

╔═══════════════════════════════════════════════════════════════════╗
║                                                                   ║
║  #680 | Adding automatic back up module to its-prod-p1p2          ║
║       https://github.com/ucsb/its.infr.util.iac/pull/680          ║
║                                                                   ║
╚═══════════════════════════════════════════════════════════════════╝

Status: Open | Reviews: ✓ Approved (2) | Comments: 5

Total: 19 | Success: 19 (18 hidden) | Failed: 0 | Pending: 0

  STATUS  NAME                DESCRIPTION       URL
  ──────  ────                ───────────       ───
  ✓       TF - its-prod-p1p2  🟢+13 🛠~3 🗑-0  https://app.terraform.io/app/...

License

MIT

Author

Eduardo Figueroa