Skip to main content
Get your first GitHub achievement in under 5 minutes. This guide walks you through installation, setup, and running your first achievement.

​
Installation

1

Clone the repository

Clone the GitHub Achievement CLI to your local machine:
git clone https://github.com/n0/GitHub-Achievement-CLI.git
cd GitHub-Achievement-CLI
2

Install dependencies

Install the required Node.js packages:
npm install
Requires Node.js 18 or higher. Check your version with node --version.
3

Build the project

Compile the TypeScript code:
npm run build
This creates the dist/ directory with compiled JavaScript files.

​
Setup Wizard

Launch the interactive setup wizard on your first run: 
npm start
The setup wizard will guide you through configuration:
1

GitHub Personal Access Token

You’ll be prompted to enter your GitHub token.
Don’t have a token? Follow these steps:
  1. Go to github.com/settings/tokens
  2. Click Generate new token (classic)
  3. Select the repo scope
  4. Copy the generated token
Paste your token when prompted:
Enter your GitHub Personal Access Token: ghp_xxxxxxxxxxxxxxxxxxxx
2

GitHub Username

Enter your GitHub username:
Enter your GitHub username: your-username
3

Target Repository

Specify a repository you own where the tool will create branches and PRs:
Enter target repository (owner/repo): your-username/your-repo
You must own this repository. The tool needs permissions to create branches, issues, and pull requests.
The wizard creates a .env file with your configuration: 
GITHUB_TOKEN=ghp_your_token_here
GITHUB_USERNAME=your-username
TARGET_REPO=your-username/your-repo

​
Your First Achievement

Let’s earn the Quickdraw achievement - it’s the fastest and simplest to complete.
1

Select 'Run Achievements'

From the main menu, use arrow keys to navigate and select Run Achievements:
┌─────────────────────────────────────┐
│  GitHub Achievement CLI             │
├─────────────────────────────────────┤
│  ❯ Run Achievements                 │
│    View Status                      │
│    List Achievements                │
│    Reset Repo History               │
│    Reconfigure                      │
│    Exit                             │
└─────────────────────────────────────┘
2

Choose Quickdraw

Select Quickdraw from the achievements list:
Select an achievement:
❯ 🤠 Quickdraw
  🎲 YOLO
  👥 Pair Extraordinaire
  🦈 Pull Shark
  🧠 Galaxy Brain
Quickdraw only has one tier and takes about 2 seconds to complete. Perfect for testing!
3

Confirm and Run

Since Quickdraw has only one tier, it runs immediately. You’ll see:
Running Quickdraw achievement...
✓ Opening issue
✓ Closing issue immediately
✓ Quickdraw achievement complete!

Achievement earned in 2 seconds

​
What Happens After Running

When you run Quickdraw, the tool:
  1. Creates an issue in your target repository
  2. Immediately closes it (within milliseconds)
  3. Triggers the achievement on your GitHub profile
GitHub may take a few minutes to display the achievement badge on your profile. Check your profile at github.com/your-username to see the Quickdraw badge appear.

​
Verify Your Achievement

Check your GitHub profile to see the new badge: 
# Open your profile in the browser
open https://github.com/your-username
The closed issue remains in your repository’s issue history. Since Quickdraw only creates one issue, cleanup is minimal.

​
Next Steps

Now that you’ve earned your first achievement, explore more:

Run More Achievements

Learn how to run multi-tier achievements like Pull Shark and Pair Extraordinaire

Track Your Progress

View status and monitor progress for achievements in progress

Set Up Helper Account

Configure a second account to unlock Galaxy Brain and YOLO achievements

Clean Up After Completion

Use Reset Repo History to squash commits and keep your repository clean

​
Common Issues

Ensure you’re using Node.js 18 or higher:
node --version
If needed, update Node.js or use a version manager like nvm:
nvm install 18
nvm use 18
Verify your token has the repo scope:
  1. Visit github.com/settings/tokens
  2. Click on your token
  3. Ensure repo is checked
  4. Generate a new token if needed and reconfigure:
npm start
# Select "Reconfigure"
Confirm:
  • You own the repository (not just have write access)
  • The repository name format is owner/repo
  • The repository exists and is not archived
Update your configuration if needed:
npm start
# Select "Reconfigure"
GitHub achievements may take a few minutes to appear on your profile. Wait 5-10 minutes and refresh your profile page.If it still doesn’t appear, verify:
  • The issue was created and closed in your repository
  • Your GitHub profile has achievements enabled (they’re public by default)
Need more help? Check the Troubleshooting guide for detailed solutions to common problems.

​
Ready for More?

View All Achievements

Explore all 5 achievements and their tiers. Learn which ones require helper accounts and how long each takes to complete.

Build docs developers (and LLMs) love

Get started for freeTalk to us