Log your GitHub Stars Contributions from the command line.

CLI: github-stars-contributions gsc

👨‍🏫 Awais taught and created this CLI project in his NodeCLI.com automation course

• 📦 Add a contribution of any type
• 🗃️ List your contributions
• 🤯 Autocomplete search with type and filter function
• 🤯 Adding YouTube? gsc CLI can fetch title, date, and description for you
• 👨‍🏫 Awais taught and created this CLI project in his NodeCLI.com automation course

Install

# Recommended.
npx github-stars-contributions

# OR an alternative global install.
npm install -g github-stars-contributions
gsc # run global alias

Usage

The CLI supports both interactive (default) and non-interactive modes for automation.

Note: The GraphQL contributions API is deprecated and will be removed on September 1, 2026. This CLI now uses the new REST contributions API by default. A --legacy-graphql flag is available on gsc add for migration until then.

Add Contributions

💬 Interactive Mode (Default)

Run gsc add (or just gsc) and answer the prompts:

gsc add
# OR
gsc a
# OR run with no command — jumps straight into add
gsc

You'll be asked:

• Contribution Type
• URL (optional)
• Title
• Description
• Date

🤖 Non-Interactive Mode (Automation)

Perfect for CI/CD pipelines and scripts:

gsc add \
  -t BLOGPOST \
  -T "My Blog Post" \
  -D "Description here" \
  -d 2025-11-22 \
  -u https://example.com \
  -x

List Contributions

💬 Interactive Mode (Default)

Show all your contributions:

gsc list
# OR
gsc l

🤖 Non-Interactive Mode (Automation)

gsc list -x

Command Reference

Basic Syntax

github-stars-contributions <command> [options]
# OR
gsc <command> [options]

Global Options

| Option | Description | |--------|-------------| | -v, --version | Output the version number | | -h, --help | Display help for command |

Commands

| Command | Alias | Description | |---------|-------|-------------| | add [options] | a | Add a new contribution (interactive by default) | | list [options] | l | List your contributions (interactive by default) | | help [command] | - | Display help for command |

add Command

Add a new contribution to your GitHub Stars profile.

Usage:

gsc add [options]
gsc a [options]

Options:

| Option | Description | Required | |--------|-------------|----------| | -t, --type <type> | Contribution type (see types below) | Yes (non-interactive) | | -T, --title <title> | Contribution title | Yes (non-interactive) | | -D, --description <description> | Contribution description | Yes (non-interactive) | | -d, --date <date> | Date in YYYY-MM-DD format (default: today) | Yes (non-interactive) | | -u, --url <url> | Contribution URL | No | | -c, --client-id <client-id> | Stable client ID for idempotent PUT updates (letters, numbers, periods, underscores, hyphens, or colons) | No | | -L, --legacy-graphql | Use the deprecated GraphQL API (removed September 1, 2026) | No | | -x, --no-interactive | Disable interactive mode | No | | -h, --help | Display help | No |

Contribution Types:

• OTHER
• FORUM
• SPEAKING
• BLOGPOST
• HACKATHON
• VIDEO_PODCAST
• ARTICLE_PUBLICATION
• EVENT_ORGANIZATION
• OPEN_SOURCE_PROJECT

Examples:

# Interactive mode (default)
gsc add

# Non-interactive mode with all options
gsc add \
  -t BLOGPOST \
  -T "My Blog Post" \
  -D "Description here" \
  -d 2025-11-22 \
  -u https://example.com \
  -x

# Non-interactive without URL
gsc add -t SPEAKING -T "Conference Talk" -D "Talked about Node.js" -d 2025-11-20 -x

# Idempotent add/update with a stable client ID
gsc add -t BLOGPOST -T "My Blog Post" -D "Description here" -d 2025-11-22 -c my-blog-post -x

# Legacy GraphQL API (deprecated — removed September 1, 2026)
gsc add -t BLOGPOST -T "My Blog Post" -D "Description here" -d 2025-11-22 -L -x

🕰️ About the Legacy GraphQL API

The old GraphQL contributions API (api-stars.github.com) is deprecated and will be removed by GitHub on September 1, 2026.

• v4 of this CLI uses the new REST contributions API by default — no flags needed.
• If you have scripts pinned to older versions or need to double-check a migration, gsc add -L (--legacy-graphql) still talks to the legacy GraphQL API until September 1, 2026.
• After that date, the flag disappears from --help and the CLI always uses REST — no code changes needed on your side, just keep the CLI updated.
• gsc remove was removed in v4 because the REST API has no delete method. Delete contributions from the GitHub Stars website instead.

list Command

List your contributions from your GitHub Stars profile.

Usage:

gsc list [options]
gsc l [options]

Options:

| Option | Description | Required | |--------|-------------|----------| | -x, --no-interactive | Disable interactive mode | No | | -h, --help | Display help | No |

Examples:

# Interactive mode (default)
gsc list

# Non-interactive mode
gsc list -x

Changelog

❯ Read the changelog here →

KEY: 📦 NEW, 👌 IMPROVE, 🐛 FIX, 📖 DOC, 🚀 RELEASE, and 🤖 TEST

I use Emoji-log, you should try it and simplify your git commits.

License & Conduct

• Thanks to the GitHub team for the awesome contributions API.
• MIT © Ahmad Awais.
• Code of Conduct.

Connect