SSH Key Management

What it does

gitswitch can force git to use a specific SSH key when you switch profiles.

gitswitch work
# Now all git operations use ~/.ssh/id_work

Why you need this

The problem

SSH key management is complex:

• You have multiple SSH keys (personal, work, client A, client B)
• SSH agent tries all keys in order until one works
• Wrong key might work by accident (if your GitHub account has multiple authorized keys)
• Slow authentication if the agent tries many wrong keys first
• Confusion about which key is actually being used

The solution

gitswitch forces a specific key per profile:

gitswitch add work "Alice" alice@company.com \
  --ssh-key ~/.ssh/id_work

When you switch to work, git uses only ~/.ssh/id_work. No guessing. No agent fallback.

How it works

gitswitch sets:

git config --global core.sshCommand \
  "ssh -i ~/.ssh/id_work -o IdentitiesOnly=yes"

The flags mean:

• -i <key> — Use this specific key
• -o IdentitiesOnly=yes — Don’t try other keys from the agent

Git respects this setting and uses only that key for all operations.

Setup

Add profile with SSH key

gitswitch add work "Alice" alice@company.com \
  --ssh-key ~/.ssh/id_work

Generate SSH keys (if you don’t have them)

# Generate a new key
ssh-keygen -t ed25519 -f ~/.ssh/id_work -C "alice@company.com"

# Add to your GitHub account:
# Go to https://github.com/settings/keys
# New SSH key → paste the contents of ~/.ssh/id_work.pub

Verify SSH key is active

After switching:

gitswitch work
git config --global core.sshCommand
# → ssh -i ~/.ssh/id_work -o IdentitiesOnly=yes

Test the key:

ssh -T git@github.com
# → Hi alice-work! You've successfully authenticated...

Multiple keys per platform

If you use multiple GitHub accounts:

# Personal account
gitswitch add personal "Alice" alice@gmail.com \
  --ssh-key ~/.ssh/id_personal

# Work account
gitswitch add work "Alice" alice@company.com \
  --ssh-key ~/.ssh/id_work

Each profile uses its own key. When you switch, the key switches too.

SSH key passphrase

If your SSH key has a passphrase:

1. Add it to your SSH agent once:

ssh-add ~/.ssh/id_work
# Enter passphrase when prompted

2. gitswitch will use the agent’s unlocked key.

Troubleshooting

Permission denied (publickey)

Permission denied (publickey).
fatal: Could not read from remote repository.

Check:

1. Is the SSH key path correct?
2. Is the key added to your GitHub account?
3. Is the passphrase in your agent?

# Verify the key path
gitswitch list work  # should show SSH key

# Test SSH
ssh -i ~/.ssh/id_work -T git@github.com

# Add to agent if needed
ssh-add ~/.ssh/id_work

Slow authentication

If SSH is slow, it might be trying multiple keys. Verify IdentitiesOnly=yes is set:

git config --global core.sshCommand
# Must include: -o IdentitiesOnly=yes

SSH agent not working

If you don’t want to use an agent:

# Generate key without passphrase
ssh-keygen -t ed25519 -f ~/.ssh/id_work -N "" -C "alice@company.com"

Per-repo SSH key override

If you need a different key for a specific repo:

cd ~/special-repo
git config --local core.sshCommand \
  "ssh -i ~/.ssh/id_special -o IdentitiesOnly=yes"

Local config takes priority over global.

Next steps

→ GPG Signing
→ GitHub Account Sync
→ Identity Awareness