Switchly

Switch between multiple GitHub accounts in one command. Manage SSH keys, Git config, and GitHub CLI auth from a single CLI—no more editing ~/.ssh/config or juggling credentials by hand.

npm install -g switchly
switchly add    # Add personal & work profiles
switchly use personal   # or switchly use work

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Usage
  • Core Commands
  • Profile Management
  • Auto-Switching
  • Directory Restriction
  • Profile Guard
  • Backup & Migration
  • Switch History
• How It Works
• Example Workflow
• Troubleshooting
• License

Features

| Feature | Description | |--------|-------------| | Profile management | Add, list, switch, edit, clone, rename, and remove profiles | | SSH key generation | Generate and wire up SSH keys per profile with ~/.ssh/config | | Git config | Switch global user.name and user.email when you switch profiles | | GitHub CLI | Use different gh auth per profile (optional PAT) | | Commit signing | Attach different signing keys (SSH or GPG) per profile | | Auto-switching | Automatically switch profiles based on directory (.switchlyrc) | | Directory binding | Bind a profile to a repo so it auto-activates when you enter it | | Directory restriction | Lock a directory to a profile—block switching to any other profile | | Profile guard | Pre-commit hook that blocks commits with the wrong identity | | Import / Export | Back up and restore profiles across machines | | Switch history | Log of every profile switch with timestamps | | Shell prompt | Show the active profile name in your terminal prompt (switchly prompt) | | Init from config | Create a profile from your existing Git/SSH setup |

Requirements

• Node.js >= 18
• Git
• SSH (for key generation)
• GitHub CLI (optional, for gh auth switching)

Installation

npm install -g switchly

Verify:

switchly --version

Quick Start

1. Add your first profile (e.g. personal):

   switchly add

   You'll be prompted for profile name, Git name/email, and optionally SSH key generation and GitHub CLI token.

2. Add another profile (e.g. work) with switchly add again.

3. Switch:

   switchly use personal
   # or
   switchly use work

   Or run switchly use with no arguments for an interactive list.

4. Clone with a profile (using the SSH host alias):

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

Usage

Core Commands

Add a profile

switchly add

Prompts for:

• Profile name (e.g. personal, work)
• Git username and email
• SSH key generation (optional)
• GitHub CLI token (optional)
• Commit signing key (optional)

List profiles

switchly list
# or
switchly ls

Example output:

GitHub Profiles

● personal
    Name:  YasserGomma
    Email: [email protected]
    SSH:   github.com-personal

○ work
    Name:  YasserGommaMostafa
    Email: [email protected]
    SSH:   github.com-work

Switch profile

switchly use personal
# or interactive:
switchly use

Check current status

switchly status
switchly status -v   # Verbose (includes SSH test)

Show profile in shell prompt

Keep the active profile name visible in your terminal prompt. After switching with switchly use (or auto-switching), the current profile is written to ~/.switchly_prompt. Use the prompt command in your prompt so it updates automatically:

Zsh (add to ~/.zshrc):

# Show [profile] or nothing when no profile is active
setopt PROMPT_SUBST
PS1='[$(switchly prompt)] %# '
# Optional: only show when a profile is set (with color):
PS1='%F{cyan}${${:-$(switchly prompt)}:+[$(switchly prompt)] }%f%# '

Bash (add to ~/.bashrc):

PS1='[$(switchly prompt)] \u@\h:\w\$ '

The prompt file is updated whenever you run switchly use, switchly remove (if the active profile changes), or when auto-switching runs (e.g. on cd with the auto hook).

List SSH keys

switchly keys

Remove a profile

switchly remove personal
switchly rm personal -f   # Skip confirmation

Profile Management

Edit a profile

Modify any field of an existing profile without re-creating it:

switchly edit personal
# or interactive selection:
switchly edit

You can update Git name/email, GitHub token, and signing configuration. If you edit the active profile, the changes are applied immediately.

Clone a profile

Duplicate an existing profile with modifications:

switchly clone personal personal-oss

Copies settings from the source profile and prompts you to adjust values and generate a new SSH key.

Rename a profile

Rename a profile and update all associated SSH keys and config:

switchly rename work work-main

This renames the SSH key files (switchly_work -> switchly_work-main), updates ~/.ssh/config, and updates any directory bindings referencing the old name.

Init from existing config

Create a profile from your current Git and SSH configuration:

switchly init

Scans your system for existing git config, SSH host entries, gh auth status, and signing config, then creates a profile from what it finds. Useful for onboarding.

Auto-Switching

Automatically switch profiles when you enter a project directory.

Set up a directory

cd ~/projects/work-repo
switchly auto set work

This creates a .switchlyrc file in the directory. When you cd into it (with the shell hook active), Switchly auto-switches to the specified profile.

Remove auto-switch

switchly auto remove

Install the shell hook

switchly auto install

This prints the hook code for your shell. Add it to your config file:

Zsh (~/.zshrc):

switchly_auto_switch() {
  switchly auto check --quiet 2>/dev/null
}
chpwd_functions=(${chpwd_functions[@]} "switchly_auto_switch")

Bash (~/.bashrc):

switchly_auto_switch() {
  switchly auto check --quiet 2>/dev/null
}
PROMPT_COMMAND="switchly_auto_switch;${PROMPT_COMMAND}"

Fish (~/.config/fish/config.fish):

function __switchly_auto_switch --on-variable PWD
  switchly auto check --quiet 2>/dev/null
end

Bind a profile to a directory

An alternative to .switchlyrc files. Bindings are stored in Switchly's config (not in the repo):

cd ~/projects/work-repo
switchly bind work

switchly bind list      # List all bindings
switchly bind remove    # Remove binding for current directory

Priority order: Restrictions > Bindings > .switchlyrc files.

Directory Restriction

Lock a directory to a specific profile. Unlike bindings (which are a soft suggestion), restrictions block switching to any other profile while inside that directory.

Restrict a directory

cd ~/projects/work-repo
switchly restrict work
# or: switchly lock work

This locks the current directory to the work profile. Any attempt to switchly use a different profile while inside this directory will be blocked. A binding is also created automatically so auto-switching works.

Override a restriction

switchly use personal --force   # Bypass the restriction

List restrictions

switchly restrict list

Remove a restriction

switchly restrict remove   # Remove restriction for current directory

Restrictions propagate to subdirectories. If you restrict ~/projects/work, all directories under it are also restricted.

Profile Guard

Prevent accidental commits with the wrong identity using a Git pre-commit hook.

Install the guard

cd ~/projects/work-repo
switchly guard install

This adds a pre-commit hook that checks if the active profile matches the expected one (from .switchlyrc or a binding). If there's a mismatch, the commit is blocked.

Remove the guard

switchly guard remove

The guard appends to existing pre-commit hooks rather than overwriting them.

Backup & Migration

Export profiles

switchly export                          # -> switchly-profiles.json
switchly export my-backup.json           # Custom filename
switchly export --include-tokens         # Include GitHub PATs (excluded by default)

Import profiles

switchly import switchly-profiles.json
switchly import backup.json --merge      # Auto-skip existing profiles
switchly import backup.json --overwrite  # Auto-replace existing profiles

When duplicates are found, you're prompted to skip, overwrite, or rename. SSH keys are not included in exports—you'll need to generate new ones after importing.

Switch History

Every profile switch is logged with a timestamp and trigger type (manual, auto, or bind).

switchly log              # Show last 20 switches
switchly log -n 50        # Show last 50
switchly log --clear      # Clear history

Example output:

Switch History

[02/03/2026, 14:30] personal -> work (manual)
[02/03/2026, 09:15] work -> personal (auto)

How It Works

SSH keys

For each profile, Switchly can create an SSH key and add a block to ~/.ssh/config:

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

Use the host alias when cloning:

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

Git config

On switchly use <profile>, global Git config is updated:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

GitHub CLI

If you store a Personal Access Token for a profile, Switchly switches gh to that account when you switch profiles.

Commit signing

You can set a different signing key (SSH or GPG) per profile so commits use the right identity.

All Commands

| Command | Description | |---------|-------------| | switchly add | Add a new profile | | switchly list / ls | List all profiles | | switchly use [profile] | Switch to a profile | | switchly edit [profile] | Edit an existing profile | | switchly clone <source> [name] | Duplicate a profile | | switchly rename <old> <new> | Rename a profile | | switchly remove [profile] / rm | Remove a profile | | switchly init | Create profile from existing config | | switchly status | Show current status | | switchly prompt | Print active profile name (for use in shell prompt) | | switchly keys | List SSH keys | | switchly auto set <profile> | Set auto-switch for current directory | | switchly auto remove | Remove .switchlyrc from current directory | | switchly auto check | Check and switch (for shell hook) | | switchly auto install | Show shell hook installation code | | switchly bind [profile] | Bind profile to current directory | | switchly bind list | List all directory bindings | | switchly bind remove | Remove binding for current directory | | switchly restrict [profile] / lock | Restrict directory to a profile (blocks switching) | | switchly restrict list | List all directory restrictions | | switchly restrict remove | Remove restriction for current directory | | switchly guard install | Install pre-commit guard hook | | switchly guard remove | Remove guard hook | | switchly export [file] | Export profiles to JSON | | switchly import <file> | Import profiles from JSON | | switchly log | Show switch history |

Example Workflow

# Morning: switch to work
switchly use work
git clone [email protected]:company/repo.git
cd repo && git pull

# Evening: switch to personal
switchly use personal
git push   # Uses personal SSH + git config

With auto-switching set up:

# One-time setup
cd ~/work/repo && switchly auto set work
cd ~/personal/repo && switchly auto set personal

# Now just cd and you're on the right profile
cd ~/work/repo      # Auto-switches to work
cd ~/personal/repo  # Auto-switches to personal

Troubleshooting

| Issue | What to try | |-------|--------------| | Permission denied (publickey) | Run switchly keys and add the listed public key to the right GitHub account under Settings > SSH and GPG keys. | | Wrong Git user on commits | Run switchly status and switchly use <profile> so the active profile matches the repo. | | gh still uses old account | Re-add the profile with switchly add and enter a valid PAT, or run gh auth login for that account. | | Host alias not found | Ensure you use the host from switchly list (e.g. github.com-personal) in clone URLs: [email protected]:user/repo.git. | | Guard blocking commits | Run switchly status to check active profile, then switchly use <expected> to switch. | | Auto-switch not working | Make sure the shell hook is installed (switchly auto install) and your shell config is sourced. |

License

MIT © Yasser Gomma