Quick Start

1. Open the TUI

gitswitch

First run automatically imports your current git config as a default profile.

You’ll see an interactive interface where you can:

• ↑/↓ to navigate profiles
• enter to switch to a profile
• a to add a new profile
• c to cycle color themes
• ? to see the quick reference

2. Add a profile

Press a in the TUI to add a new profile. You’ll be prompted for:

• Nickname — short name like work, oss, client-a
• Full Name — name to appear on commits
• Email — git commit email
• SSH Key (optional) — path to SSH private key
• GPG Key (optional) — GPG signing key ID
• GitHub Username (optional) — for gh auth switch integration

Example:

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

3. Switch profiles

Interactive TUI

gitswitch

Use arrow keys to select a profile and press enter to switch.

Quick switch (no UI)

gitswitch work

Switches immediately and exits. Perfect for scripts or when you already know the profile.

4. Set up shell integration

One command sets up everything:

gitswitch install

This adds:

• Prompt segment — shows your active identity in your shell prompt
• Identity nudge — when you cd into a repo, suggests the identity you usually use there
• Tab completion — complete gitswitch commands and profile names

Supports: Starship, oh-my-zsh, Powerlevel10k, raw zsh/bash/fish.

After running, reload your shell:

source ~/.zshrc   # or open a new terminal

Common workflows

Contractor with multiple clients

gitswitch add clienta "Your Name" you@clienta.com \
  --ssh-key ~/.ssh/id_clienta

gitswitch add clientb "Your Name" you@clientb.com \
  --ssh-key ~/.ssh/id_clientb

# Before working on client A's repo:
gitswitch clienta

Open source + work

gitswitch add oss "Your Name" public@github.com \
  --gh-user yourhandle-oss

gitswitch add day "Your Name" you@company.com \
  --gh-user yourhandle-work

# Before opening an OSS PR:
gitswitch oss

Multi-account GitHub

gitswitch add personal "Alice" alice@gmail.com \
  --ssh-key ~/.ssh/id_personal \
  --gh-user alice

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

Auto-switch per repo

Pin a permanent identity to a repo:

cd ~/my-work-project
gitswitch pin work

Now every time you enter this repo, gitswitch will suggest (or automatically switch to) the work identity.

Remove the pin:

gitswitch unpin

Next steps

→ Feature Overview
→ CLI Reference
→ Real-world Scenarios