prctrl 0.9.1

Terminal-native GitHub PR management. Stay on top of code reviews without leaving your terminal.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165

# timeline

**Show the chronological timeline of events on a PR (reviews, comments, labels, CI, etc.).**

The `timeline` command displays a chronological history of all events on a PR — who requested reviews, when reviews were submitted, comments added, labels changed, branch updates, and more. It's like a "git log" for the PR's lifecycle.

## When to Use

- Understand the full history of a PR before diving into review
- See when and why review requests were made
- Track down who made specific comments or requested changes
- Identify bottlenecks in the PR review process
- See if a PR has been sitting idle or has active discussion

## Synopsis

```bash
prctrl timeline [OPTIONS]
```

## Options

| Flag | Description | Default |
|------|-------------|---------|
| `PR_NUMBER` | Target a specific PR by number | Interactive selection |
| `--pr, -p` | Target a specific PR by number (global) | Interactive selection |
| `--pr-numbers` | Show timeline for multiple PRs (comma-separated) | Single PR |
| `--all, -a` | Show timeline for all pending reviews (no interactive selection) | `false` |
| `--dry-run, -n` | Preview which PRs would be shown without displaying timelines | `false` |
| `--json` | Output as JSON for scripting | `false` |
| `--repo` | Filter by repository name (partial match, case-insensitive) | All repos |
| `--author` | Filter by author username (partial match, case-insensitive) | All authors |
| `-P, --priority` | Show priority score for each PR (1-5 stars based on age and size) | `false` |
| `-s, --since-days <DAYS>` | Only show PRs created since this many days ago | All ages |

## Examples

```bash
# Show timeline for a specific PR
prctrl timeline --pr 4821

# Show timelines for multiple PRs at once (fetched in parallel)
prctrl timeline --pr-numbers 4821,4822,4823

# Show timeline for all pending reviews (no interactive selection)
prctrl timeline --all

# Preview which PRs would be shown (dry run)
prctrl timeline --all --dry-run

# Interactive mode (select from pending reviews)
prctrl timeline

# JSON output for integration
prctrl timeline --pr 4821 --json

# Filter to a specific repo
prctrl timeline --repo frontend

# Filter to a specific author
prctrl timeline --author sarah_dev

# Combine filters
prctrl timeline --repo myorg --author reviewer1

# Show with priority scores to identify urgent PRs
prctrl timeline --priority

# Show timelines for recent PRs only (last 7 days)
prctrl timeline --since-days 7

# Combine filters
prctrl timeline --repo myorg --author reviewer1 --since-days 14
```

## Output

```
════════════════════════════════════════════════════════════
📜 PR #4821 — feat: add CSV export Timeline
════════════════════════════════════════════════════════════

  📊 Summary: 3 reviews, 7 comments, 2 label changes, 3 other events
  ────────────────────────────────────────────────────────────

  2026-03-15 09:30  📣  PR marked as ready for review by @sarah_dev

  2026-03-15 09:31  👥  Review requested from @reviewer1

  2026-03-15 09:31  👥  Review requested from @reviewer2

  2026-03-15 14:20  💬  Comment by @reviewer1: "Looking good overall..."

  2026-03-16 10:15  🔁  CHANGES_REQUESTED by @reviewer1 review: "Please fix the..."

  2026-03-17 11:00  🏷️  Labeled with *needs-changes* by @reviewer1

  2026-03-18 16:30  💬  Comment by @sarah_dev: "Fixed! PTAL"

  2026-03-19 09:00  ✅  APPROVED by @reviewer1 review: "LGTM now"

  2026-03-19 09:05  ✅  APPROVED by @reviewer2 review

  ────────────────────────────────────────────────────────────
  🔗 https://github.com/myorg/frontend/pull/4821
════════════════════════════════════════════════════════════
```

## Event Types

The timeline captures various event types:

| Icon | Event | Description |
|------|-------|-------------|
| `📣` | `ready_for_review` | PR marked as ready for review |
| `👥` | `review_requested` | Review requested from user/team |
| `✅` | `PullRequestReview` (APPROVED) | PR approved |
| `🔁` | `PullRequestReview` (CHANGES_REQUESTED) | Changes requested |
| `💬` | `Comment` / `IssueComment` | General comment |
| `🏷️` | `labeled` / `unlabeled` | Label added/removed |
| `👤` | `assigned` / `unassigned` | Assignee changed |
| `⚡` | `head_ref_force_pushed` | Branch force-pushed |
| `🔀` | `merged` | PR merged |
| `❌` | `closed` | PR closed (not merged) |
| `🔄` | `reopened` | PR reopened |
| `🔒` / `🔓` | `locked` / `unlocked` | PR locked/unlocked |

## JSON Output

When `--json` is specified, outputs a structured JSON array of events:

```json
{
  "pr_number": 4821,
  "pr_title": "feat: add CSV export",
  "repo": "myorg/frontend",
  "url": "https://github.com/myorg/frontend/pull/4821",
  "priority_score": 4,
  "events": [
    {
      "event": "PullRequestReview",
      "created_at": "2026-03-19T09:00:00Z",
      "actor": "reviewer1",
      "data": {
        "review_state": "APPROVED",
        "body_preview": "LGTM now"
      }
    },
    ...
  ]
}
```

## Tips

- Use `--json` for integration with scripts, dashboards, or custom tooling
- Timeline shows events chronologically (oldest first)
- Summary shows counts of reviews, comments, and label changes
- Great for understanding why a PR has been sitting — check the timeline to see if it's actively being worked on or abandoned

## Related Commands

- [`info`](./info.md) — Show full PR details (description, labels, reviewers)
- [`activity`](./activity.md) — Show your recent review activity across all PRs
- [`chase`](./chase.md) — Send follow-up reminders to stale PR authors