ghswap

A command-line tool for managing multiple GitHub accounts on the same machine. Seamlessly switch between different Git configurations, SSH keys, and GitHub CLI authentication contexts.

Table of Contents

• Installation
• Quick Start
• Features
• Usage
• Configuration
• SSH Setup
• Auto-Switching
• Troubleshooting
• Requirements
• License

Installation

Install globally via npm:

npm install -g ghswap

Quick Start

Get started in less than 2 minutes:

# 1. Install
npm install -g ghswap

# 2. Add your first account
ghswap add

# 3. Switch accounts anytime
ghswap work
ghswap personal

# 4. Clone and work normally
git clone [email protected]:username/repo.git
git commit -m "your changes"
git push

That's it! The tool handles:

• ✅ Git config (user.name, user.email)
• ✅ SSH key management
• ✅ GitHub CLI authentication (optional)

Optional: Enable auto-switching based on directory:

ghswap setup  # Add output to ~/.zshrc or ~/.bashrc

Features

• Git Configuration Management - Automatically sets user.name and user.email
• SSH Key Switching - Manages SSH keys in ssh-agent
• GitHub CLI Integration - Authenticates gh CLI when tokens are provided
• Directory-Based Auto-Detection - Automatically switches accounts based on current directory
• Interactive Account Selection - User-friendly menu for account switching
• Shell Integration - Optional auto-switching on directory change
• Safe SSH Config Management - Non-destructive updates to ~/.ssh/config

Usage

Available Commands

ghswap                 # Interactive account selection menu
ghswap <account>       # Switch to a specific account
ghswap add             # Add a new account with guided setup
ghswap auto            # Auto-detect account based on current directory
ghswap list            # List all configured accounts
ghswap setup           # Display shell hook setup instructions
ghswap ssh-config      # Generate SSH configuration automatically
ghswap ssh-init        # Check SSH keys and display generation commands
ghswap help            # Display help information
ghswap --version       # Show version number

Interactive Account Addition

When you run ghswap add, you'll be prompted for:

1. Account name (e.g., "work", "personal")
2. Git username (e.g., "John Doe")
3. Git email (e.g., "[email protected]")
4. GitHub username (e.g., "johndoe")
5. Project directory (e.g., "~/projects/work")

The tool will then:

• Generate an SSH keypair automatically
• Add the account to your configuration
• Update your SSH config with the host alias
• Create directory mapping for auto-switching
• Display the public key for adding to GitHub
• (macOS only) Copy the public key to clipboard

Example Session

$ ghswap add

Add New GitHub Account

Account name: work
Git username: John Doe
Git email: [email protected]
GitHub username: johndoe
Project directory: ~/projects/work

Setting up account...

Generating SSH key...
SSH key generated
Added to configuration
SSH config updated

Copy this SSH public key to GitHub:
────────────────────────────────────────────────────────
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... [email protected]
────────────────────────────────────────────────────────

Next steps:
1. Go to: https://github.com/settings/ssh/new
2. Title: "work - MacBook"
3. Paste the key above
4. Click "Add SSH key"

Test the connection:
   ssh -T [email protected]

Auto-switch enabled for: ~/projects/work

Switch to this account and start working:
   ghswap work
   git clone [email protected]:johndoe/repo.git
   # Work normally - ghswap has configured everything!

Configuration

Configuration is stored in ~/.ghswap.json:

{
  "accounts": [
    {
      "name": "personal",
      "gitName": "John Doe",
      "gitEmail": "[email protected]",
      "sshKey": "~/.ssh/id_rsa_personal",
      "ghToken": "ghp_xxxxxxxxxxxx"
    },
    {
      "name": "work",
      "gitName": "John Doe",
      "gitEmail": "[email protected]",
      "sshKey": "~/.ssh/id_rsa_work"
    }
  ],
  "directoryMappings": {
    "~/projects/personal": "personal",
    "~/projects/work": "work"
  },
  "defaultAccount": "personal"
}

Configuration Fields

• accounts - Array of GitHub account configurations
  • name - Unique identifier for the account
  • gitName - Git user.name value
  • gitEmail - Git user.email value
  • sshKey - Path to SSH private key
  • ghToken - (Optional) GitHub CLI authentication token
• directoryMappings - Maps directories to accounts for auto-switching
• defaultAccount - Account to use when no directory mapping matches

SSH Setup

Automated SSH Configuration

Generate SSH configuration entries for all accounts:

ghswap ssh-config

This command will:

• Generate SSH config entries for each account
• Back up your existing ~/.ssh/config
• Add a managed block to your SSH config
• Display clone URLs for each account

The generated SSH config uses host aliases:

# BEGIN GHSWAP MANAGED BLOCK

Host github.com-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_rsa_personal
  IdentitiesOnly yes

Host github.com-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_rsa_work
  IdentitiesOnly yes

# END GHSWAP MANAGED BLOCK

This approach is safe to run multiple times - only the managed block is replaced, preserving your other SSH configurations.

SSH Key Generation

Check which SSH keys are missing:

ghswap ssh-init

Or generate keys manually:

ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/id_rsa_personal
ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/id_rsa_work

Add the public keys to their respective GitHub accounts:

cat ~/.ssh/id_rsa_personal.pub
cat ~/.ssh/id_rsa_work.pub

Cloning Repositories

Simple Method (Recommended):

Just switch to your account first, then use normal GitHub URLs:

ghswap work
git clone [email protected]:username/repo.git

Advanced: Using Host Aliases (Optional)

If you prefer, you can use host aliases to specify the account in the clone URL:

git clone [email protected]:username/repo.git
git clone [email protected]:username/repo.git

This is useful if you want to clone repos for multiple accounts without switching, but most users won't need this.

Auto-Switching

Manual Auto-Detection

Switch accounts based on the current directory:

cd ~/projects/work
ghswap auto

Automatic Directory-Based Switching

For automatic switching when changing directories:

1. Generate the shell hook:

   ghswap setup

2. Add the output to your shell configuration:

   # For zsh
   echo "$(ghswap setup)" >> ~/.zshrc
   
   # For bash
   echo "$(ghswap setup)" >> ~/.bashrc

3. Reload your shell:

   source ~/.zshrc  # or source ~/.bashrc

Now accounts will switch automatically:

cd ~/projects/personal  # Automatically switches to personal account
cd ~/projects/work      # Automatically switches to work account

Troubleshooting

SSH Key Issues

Problem: SSH key not working

Solution:

# List currently loaded keys
ssh-add -l

# Manually add a key
ssh-add ~/.ssh/id_rsa_work

# Test the connection
ssh -T [email protected]

Git Configuration Issues

Problem: Git config not switching

Solutions:

• Verify you're in a git repository for local config changes
• Check current settings: git config --list
• Try switching with global scope explicitly

Auto-Switch Not Working

Problem: Directory-based auto-switching not working

Solutions:

• Ensure directory mappings use absolute paths or ~ prefix
• Verify shell hooks are properly installed
• Reload your shell after adding hooks: source ~/.zshrc
• Check that directory mappings in ~/.ghswap.json match your project paths

Permission Errors

Problem: Permission denied when accessing SSH keys

Solution:

# Fix SSH key permissions
chmod 600 ~/.ssh/id_rsa_*
chmod 644 ~/.ssh/id_rsa_*.pub

Requirements

• Node.js >= 14.0.0
• Git - For git configuration management
• SSH - For SSH key management
• GitHub CLI (optional) - For gh authentication

Security Best Practices

1. Protect your configuration file:

   echo ".ghswap.json" >> ~/.gitignore_global

2. Never commit tokens - The ghToken field is optional and should be used with caution

3. Use strong SSH keys - The tool generates ed25519 keys by default, which are secure and modern

4. Regular key rotation - Periodically update your SSH keys and remove old ones from GitHub

Contributing

Issues and pull requests are welcome at github.com/shubhamV123/ghswap.

License

MIT License - see LICENSE file for details.

Author

Shubham Verma

Support

• Report issues: GitHub Issues
• Documentation: GitHub Repository