Skip to main content

​
Setup Wizard

When you run GitHub Achievement CLI for the first time, you’ll be guided through an interactive setup wizard that configures everything you need.
1

Start the Setup Wizard

Run the CLI for the first time:
npm start
The setup wizard will automatically launch if no configuration is found.
2

Enter Your GitHub Token

Provide your GitHub Personal Access Token when prompted:
  • Token format: ghp_... or github_pat_...
  • Required scope: repo (full control of private repositories)
  • Generate token here
Your token is validated immediately. The wizard will authenticate and display your username.
3

Specify Target Repository

Enter the repository where achievements will be created:
  • Format: owner/repo (e.g., myusername/GitHub-Achievements-Manager)
  • Default suggestion: your-username/GitHub-Achievements-Manager
  • The repository must exist and you must have write access
The tool will create branches, commits, PRs, and issues in this repository. Choose a dedicated repository or one you don’t mind filling with achievement activity.
4

Discussions Check

The wizard automatically checks if GitHub Discussions are enabled on your repository.
  • If enabled: You’ll be prompted to configure Galaxy Brain/YOLO achievements (requires helper account)
  • If disabled: Setup continues without Galaxy Brain/YOLO support
To enable Discussions: Go to your repository Settings → Features → Check “Discussions”
5

Helper Account (Optional)

If Discussions are enabled, you’ll be asked if you want to configure Galaxy Brain and YOLO achievements.These achievements require a second GitHub account:
  • Helper account creates discussion questions or PR reviews
  • Your main account responds to earn achievements
If you choose to configure:
  1. Provide token from your second GitHub account
  2. Must be different from your main account
  3. Helper account needs collaborator access to your repository
The wizard can automatically invite the helper account as a collaborator.
6

Configuration Saved

The wizard creates a .env file in your project directory with all settings:
  • GitHub token and username
  • Target repository
  • Default coauthor information
  • Optional helper account token
You’ll be asked if you want to star the GitHub Achievement CLI repository. This is optional but appreciated!

​
Configuration Options During Setup

The setup wizard configures these values automatically:
​
githubToken
string
required
Your GitHub Personal Access Token (main account)
​
githubUsername
string
required
Your GitHub username (auto-detected from token)
​
targetRepo
string
required
Repository in format owner/repo where achievements will be created
​
coauthorName
string
default:"n0"
Coauthor name for Pair Extraordinaire achievement commits
​
coauthorEmail
string
default:"[email protected]"
Coauthor email for Pair Extraordinaire achievement commits
​
branchPrefix
string
default:"achievement"
Prefix for created branches (e.g., achievement/pull-shark-1)
​
delayMs
number
default:"1000"
Delay in milliseconds between operations
​
helperToken
string
GitHub token from helper account (second account) for Galaxy Brain/YOLO

​
.env File Creation

The wizard creates a .env file with this structure: 
# GitHub Achievements Manager Configuration
# Generated by setup wizard on [timestamp]

# ===========================================
# REQUIRED SETTINGS
# ===========================================

# Your GitHub Personal Access Token
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Your GitHub username
GITHUB_USERNAME=your-username

# Target repository for achievement creation
TARGET_REPO=your-username/your-repo

# ===========================================
# OPTIONAL SETTINGS
# ===========================================

# Coauthor for Pair Extraordinaire achievement
COAUTHOR_NAME=n0
[email protected]

# Branch prefix for created branches
BRANCH_PREFIX=achievement

# Delay between operations in milliseconds
DELAY_MS=1000

# ===========================================
# ADVANCED SETTINGS
# ===========================================

# Enable verbose logging
VERBOSE=false

# Enable test/dry-run mode
TEST_MODE=false

# Batch size for parallel operations
BATCH_SIZE=5

# Log level: debug, info, warn, error
LOG_LEVEL=info

​
Verifying Configuration

After setup completes, verify your configuration:
1

Check .env File

Ensure the .env file exists in your project root:
cat .env
Verify all required fields are populated with your information.
2

Test Connection

Launch the CLI to verify authentication:
npm start
You should see the main menu without any errors.
3

Check Repository Access

From the main menu, select View Status to confirm:
  • Repository is accessible
  • Token has correct permissions
  • Current achievement progress is loaded

​
Re-running Setup

To reconfigure your settings:
  1. From the CLI menu: Select Reconfigure option
  2. Delete .env: Remove the .env file and restart the CLI
  3. Manual edit: Edit .env directly (see Environment Variables)
If you change your TARGET_REPO, your achievement progress will reset. Progress is tracked per-repository.

​
Troubleshooting Setup

​
Token Validation Failed

Error: “Token validation failed. Check your token and try again.” Solutions:
  • Verify token format starts with ghp_ or github_pat_
  • Ensure token has repo scope selected
  • Generate a new token if the old one expired
  • Check your internet connection

​
Repository Not Found

Error: “Could not access repository. Check the name and your permissions.” Solutions:
  • Verify repository exists on GitHub
  • Check format is owner/repo (e.g., myusername/my-repo)
  • Ensure you have write access to the repository
  • Make sure repository is not archived

​
Helper Account Must Be Different

Error: “Helper account must be different from your main account” Solutions:
  • Use a token from a different GitHub account
  • Create a second GitHub account if needed (free)
  • You can skip helper account setup and configure it later

​
Next Steps

Environment Variables

Complete reference of all configuration options

GitHub Tokens

Learn about token requirements and security

Run Achievements

Start earning achievements

Troubleshooting

Common issues and solutions

Build docs developers (and LLMs) love

Get started for freeTalk to us