github activity

A lightweight, cross-platform CLI tool to inspect recent GitHub user activity using GitHub’s public Events API.

gh-activity is designed for developers who want quick, readable insights into pushes, pull requests, and issues — directly from the terminal.

---

Table of Contents

• Get Started

• Installation

  • Windows
  • Linux
  • macOS

• Authentication

• Usage

  • Scopes & Commands
  • Repository
  • Pushes
  • Pull Requests
  • Issues
  • Watches
  • Summary

• Flags

• Notes

• License

---

Get Started

gh-activity is shipped as a single self-contained binary.

You download the release for your operating system, add it to your PATH, and start using it immediately — no Go installation required.

---

Installation

Releases are distributed as ZIP archives that already contain the correctly named binary inside a bin/ directory.

General Structure (inside the archive)

gh-activity/
└── bin/
    └── gh-activity        (or gh-activity.exe on Windows)

You only need to add the bin/ directory to your system PATH.

---

Windows

1. Download the latest release:

gh-activity-windows-amd64.zip

2. Extract the archive
3. Add the extracted bin folder to Environment Variables → PATH
4. Open a new terminal and verify:

gh-activity --help

---

Linux

1. Download:

gh-activity-linux-amd64.zip

2. Extract:

unzip gh-activity-linux-amd64.zip

3. Add bin/ to PATH:

export PATH=$PATH:/path/to/gh-activity/bin

4. (Optional) If the binary is not executable:

chmod +x gh-activity

5. Verify:

gh-activity --help

https://roadmap.sh/projects/github-user-activity

macOS

1. Download the correct archive:

• Intel: gh-activity-darwin-amd64.zip
• Apple Silicon: gh-activity-darwin-arm64.zip

2. Extract:

unzip gh-activity-darwin-amd64.zip

3. Add bin/ to PATH

4. (Optional) If the binary is not executable:

chmod +x gh-activity

5. Verify:

gh-activity --help

---

Authentication

🔐 Creating a GitHub Personal Access Token

To avoid API rate limits, you can create a GitHub Personal Access Token.

1. Go to GitHub → Settings

2. Open Developer settings (left sidebar)

3. Click Personal access tokens

4. Select Tokens (classic)

5. Click Generate new token

6. Give it a name (e.g. gh-activity)

7. Select scopes:

   • ✅ public_repo (recommended)

8. Generate the token and copy it immediately

Then set it in the CLI:

gh-activity set token <your-token>

What happens internally

• Token is stored locally at:

~/.gh-activity/config.json

• File permissions are restricted (0600)
• A timestamp is recorded
• You’ll receive a warning if the token is older than 90 days

To view the saved token:

gh-activity get token

### Authentication behavior

- The CLI prints a single auth status message once per run (token vs no token).
- If GitHub returns “Bad credentials”, the saved token is removed and the request is retried unauthenticated.
- Unauthenticated requests are rate-limited — set a valid token to avoid hitting limits.

---

Usage

Scopes & Commands

The CLI follows a strict positional structure:

gh-activity <scope> <entity> <command> [flags]

Currently supported scopes:

• user
• repo

Repository

View repository metadata and a summary of recent events in one go.

Repo Info

gh-activity repo <owner>/<repo> info [--limit N]

Shows a two-column table with key fields, followed by a compact events summary.

Field order:

1. Name
2. Description
3. Primary Language
4. License
5. Visibility
6. Stars
7. Forks
8. Open Issues
9. Created
10. Last Updated
11. Last Push
12. Topics

Events order: Push, Issues, Watch, Pull Requests.

Example

- Using GitHub Token for authentication.

📦 Repository Info

FIELD               VALUE
------------------  --------------------------------------------
Name                ndk123-web/github-activity
Description         A lightweight, cross-platform CLI tool to inspect recent GitHub user activity
Primary Language    Go
License             MIT
Visibility          Public
Stars               1
Forks               0
Open Issues         0
Created             2025-12-24
Last Updated        2025-12-28
Last Push           2025-12-28
Topics              [cli] [command-line-tool] [cross-platform] [golang] [tool]

📦 Repository Events (recent)
--------------------
EVENT          COUNT
-------------  -----
Push Events       20
Issues             2
Watch Events       1
Pull Requests      0

--limit controls the number of recent events considered when building the summary.

---

Pushes

View recent push activity by a user, grouped by repository.

gh-activity user <username> pushes [--limit N]

Flags:

• --limit (optional) — Number of recent push events (default: 2)

---

Pull Requests

View pull request activity filtered by state.

gh-activity user <username> pulls --state <open|closed|merged> [--limit N]

Flags:

• --state (required) — open, closed, or merged
• --limit (optional) — Number of results (default: 2)

---

Issues

View issue activity (pull requests are automatically excluded).

gh-activity user <username> issues --state <open|closed> [--limit N]

Flags:

• --state (required) — open or closed
• --limit (optional) — Number of results (default: 2)

---

Watches

View watch/star events grouped by repository.

gh-activity user <username> watches [--limit N]

What it shows:

• Count of recent WatchEvent per repository for the user’s recent activity window
• An overview summary and a neat table like other commands

Flags:

• --limit (optional) — Number of distinct repositories to include (default: 2, max: 50)

Example:

gh-activity user octocat watches --limit 5

Summary

Generate a combined summary of recent activity for a user (pushes, pull requests, issues, watches) with clean, tabular counts and an aggregated top repositories list.

Command

gh-activity user <username> summary [--limit N]

Sample Output

📊 Activity Summary (last 10 events)

Metric                     Count
Total Events               54
Total Push Events          45
Total Pull Request Events  2
Total Issues Events        2
Total Watch Events         5

Top Repositories (by total activity):
------------------------------------------
ndk123-web/DSA                 21 events
ndk123-web/github-activity     20 events
ndk123-web/observability-learning 4 events
ndk123-web/study-sync-ai       4 events
spf13/cobra                    1 events

--limit semantics

• Current behavior: --limit N caps the number of distinct repositories included per event type (pushes, pulls, issues, watches). It does not limit the total events processed globally.
• If you prefer --limit to mean “process only the last N events overall”, open an issue — this can be switched to a global event cap.

---

Flags

--limit

• Controls how many events are displayed
• Default: 2

--state

• Required for pulls and issues
• Pull requests: open, closed, merged
• Issues: open, closed

---

Summary

Generate a combined summary of recent activity for a user (pushes, pull requests, issues, watches) with clean, tabular counts and an aggregated top repositories list.

Command

gh-activity user <username> summary [--limit N]

Sample Output

📊 Activity Summary (last 10 events)

Metric                     Count
Total Events               54
Total Push Events          45
Total Pull Request Events  2
Total Issues Events        2
Total Watch Events         5

Top Repositories (by total activity):
------------------------------------------
ndk123-web/DSA                 21 events
ndk123-web/github-activity     20 events
ndk123-web/observability-learning 4 events
ndk123-web/study-sync-ai       4 events
spf13/cobra                    1 events

--limit semantics

• Current behavior: --limit N caps the number of distinct repositories included per event type (pushes, pulls, issues, watches). It does not limit the total events processed globally.
• If you prefer --limit to mean “process only the last N events overall”, open an issue — this can be switched to a global event cap.

---

For internal architecture and extension guidance, see docs/developer-guide.md.

Notes

• Data is fetched from GitHub’s Events API
• Events are recent activity only (not full history)
• One push event ≠ one commit
• Output is optimized for terminal readability and scripting

Formatting notes

• Long descriptions are normalized (whitespace collapsed) and truncated to avoid breaking table layout.
• Topic tags render as bracketed labels: [tag1] [tag2] ….

---

License

MIT License. See LICENSE.

---