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.

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

`bash
npm install -g switchly
`

Verify:

`bash
switchly --version
`

---

Quick Start

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

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

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

`bash
git clone git@github.com-personal:username/repo.git
`

---

Usage

$3

#### Add a profile

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

`bash
switchly list


or


switchly ls
`

Example output:

`
GitHub Profiles

● personal
Name: YasserGomma
Email: yassergomma204@gmail.com
SSH: github.com-personal

○ work
Name: YasserGommaMostafa
Email: yasser@company.com
SSH: github.com-work
`

#### Switch profile

`bash
switchly use personal


or interactive:


switchly use
`

#### Check current status

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

`bash


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):

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

`bash
switchly keys
`

#### Remove a profile

`bash
switchly remove personal
switchly rm personal -f # Skip confirmation
`

---

$3

#### Edit a profile

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

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

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

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

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

---

$3

Automatically switch profiles when you enter a project directory.

#### Set up a directory

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

`bash
switchly auto remove
`

#### Install the shell hook

`bash
switchly auto install
`

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

Zsh (~/.zshrc):
`bash
switchly_auto_switch() {
switchly auto check --quiet 2>/dev/null
}
chpwd_functions=(${chpwd_functions[@]} "switchly_auto_switch")
`

Bash (~/.bashrc):
`bash
switchly_auto_switch() {
switchly auto check --quiet 2>/dev/null
}
PROMPT_COMMAND="switchly_auto_switch;${PROMPT_COMMAND}"
`

Fish (~/.config/fish/config.fish):
`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):

`bash
cd ~/projects/work-repo
switchly bind work
`

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

Priority order: Restrictions > Bindings > .switchlyrc files.

---

$3

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

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

`bash
switchly use personal --force # Bypass the restriction
`

#### List restrictions

`bash
switchly restrict list
`

#### Remove a restriction

`bash
switchly restrict remove # Remove restriction for current directory
`

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

---

$3

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

#### Install the guard

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

`bash
switchly guard remove
`

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

---

$3

#### Export profiles

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

#### Import profiles

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

---

$3

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

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

$3

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:

`bash
git clone git@github.com-personal:owner/repo.git
`

$3

On switchly use , global Git config is updated:

`bash
git config --global user.name "Your Name"
git config --global user.email "your@email.com"
`

$3

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

$3

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 [name] | Duplicate a profile |
| switchly rename | 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 | 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 | Import profiles from JSON |
| switchly log | Show switch history |

---

Example Workflow

`bash


Morning: switch to work

switchly use work
git clone git@github.com-work: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:

`bash


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 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: git@github.com-personal:user/repo.git. |
| Guard blocking commits | Run switchly status to check active profile, then switchly use 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