ghswap/README.md

Easy GitHub account switching - manage multiple GitHub accounts with seamless context switching for Git config, SSH keys, and GitHub CLI

# 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](#installation)
- [Quick Start](#quick-start)
- [Features](#features)
- [Usage](#usage)
- [Configuration](#configuration)
- [SSH Setup](#ssh-setup)
- [Auto-Switching](#auto-switching)
- [Troubleshooting](#troubleshooting)
- [Requirements](#requirements)
- [License](#license)

## Installation

Install globally via npm:

```bash
npm install -g ghswap
```

## Quick Start

Get started in less than 2 minutes:

```bash
# 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 git@github.com: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:
```bash
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

```bash
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., "you@company.com")
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

```bash
$ ghswap add

Add New GitHub Account

Account name: work
Git username: John Doe
Git email: john@company.com
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... john@company.com
────────────────────────────────────────────────────────

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 git@github.com

Auto-switch enabled for: ~/projects/work

Switch to this account and start working:
   ghswap work
   git clone git@github.com:johndoe/repo.git
   # Work normally - ghswap has configured everything!
```

## Configuration

Configuration is stored in `~/.ghswap.json`:

```json
{
  "accounts": [
    {
      "name": "personal",
      "gitName": "John Doe",
      "gitEmail": "john@personal.com",
      "sshKey": "~/.ssh/id_rsa_personal",
      "ghToken": "ghp_xxxxxxxxxxxx"
    },
    {
      "name": "work",
      "gitName": "John Doe",
      "gitEmail": "john@company.com",
      "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:

```bash
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:

```bash
ghswap ssh-init
```

Or generate keys manually:

```bash
ssh-keygen -t ed25519 -C "your@email.com" -f ~/.ssh/id_rsa_personal
ssh-keygen -t ed25519 -C "work@company.com" -f ~/.ssh/id_rsa_work
```

Add the public keys to their respective GitHub accounts:

```bash
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:

```bash
ghswap work
git clone git@github.com:username/repo.git
```

**Advanced: Using Host Aliases (Optional)**

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

```bash
git clone git@github.com-personal:username/repo.git
git clone git@github.com-work: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:

```bash
cd ~/projects/work
ghswap auto
```

### Automatic Directory-Based Switching

For automatic switching when changing directories:

1. Generate the shell hook:

   ```bash
   ghswap setup
   ```

2. Add the output to your shell configuration:

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

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

3. Reload your shell:
   ```bash
   source ~/.zshrc  # or source ~/.bashrc
   ```

Now accounts will switch automatically:

```bash
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:**

```bash
# List currently loaded keys
ssh-add -l

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

# Test the connection
ssh -T git@github.com-work
```

### 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:**

```bash
# 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:**

   ```bash
   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](https://github.com/shubhamV123/ghswap).

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Author

Shubham Verma

## Support

- Report issues: [GitHub Issues](https://github.com/shubhamV123/ghswap/issues)
- Documentation: [GitHub Repository](https://github.com/shubhamV123/ghswap)