gitswitch --help groups commands the same way this page does.

Plus gitswitch with no arguments, and gitswitch <nickname> as a shortcut.

gitswitch — the interactive UI

gitswitch

Three tabs — Accounts, Utilities, Settings — reachable with 1 2 3, tab / shift+tab, or a mouse click.

The mouse works throughout: hover moves focus, clicks select and toggle, the scroll wheel moves through lists.

Utilities tab — three toggles: Shell Integration, Session Isolation, HTTPS Credential Helper. Settings tab — theme, config file location (opens it in $EDITOR), and the gs shell alias (rename with e, toggle with enter).

First launch on a machine with no profiles yet checks for git/gh and offers to install whichever's missing, then runs a short onboarding wizard, which scans your gh logins and ~/.ssh/ keys and offers to import them.

gitswitch <nickname> — quick switch

gitswitch work

✓ Switched to 'work' — Alice Smith <alice@company.com>

Identical to gitswitch switch work. Exits non-zero if the nickname doesn't exist.

Identity

add

gitswitch add <nickname> <user-name> <email> [flags]

gitswitch add personal "Alice Smith" alice@gmail.com

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

Prefer not typing all that? gitswitch login fills it in from GitHub.

switch

gitswitch switch <nickname>

Same as gitswitch <nickname>. See Commit Identity for exactly what gets written.

list

gitswitch list [--json]

✓  personal        Alice Smith <alice@gmail.com>
   work            Alice Smith <alice@company.com>

✓ marks your active global account.

current

gitswitch current [--json | --short | --prompt]

work — Alice Smith <alice@company.com>  (pinned to this repo)
HTTPS credential helper: active

The suffix names the scope: nothing for global, (pinned to this repo), or (this terminal's session). If a pin exists but Session Isolation is off, it says so.

Prints No active profile if nothing has been applied yet.

remove

gitswitch remove <nickname>

Deletes the account. Does not revert git config that was applied while it was active, and doesn't revoke anything on GitHub. Any history entries under that nickname stay behind harmlessly.

init

gitswitch init

Imports your current --global user.name / user.email as an account named default. Runs automatically on first use if you have no accounts.

Session Isolation

pin

gitswitch pin [nickname]

Writes the account's full identity into this repo's local git config — user.name, user.email, user.signingkey/gpg.format, core.sshCommand. Your global identity is untouched.

With no nickname, it adopts the repo's existing local user.email and matches it to a stored account.

Turns Session Isolation on automatically if it was off, since a pin can't take effect without it. Must be run inside a git repo.

unpin

gitswitch unpin

Removes those keys from the repo's local config; the repo falls back to your global identity. Must be run inside a git repo.

shell

gitswitch shell [flags]

Interactive wizard with three steps, each skippable:

1. Shell integration — prompt segment, nudge on cd, tab completion, gs alias
2. HTTPS credential routing — right token per repo on push
3. Session Isolation — right gh account per repo, and working pins

Safe to re-run — everything lives between # gitswitch markers and gets replaced in place, never duplicated. Re-run it after an upgrade to pick up an improved hook, or to repair credential-helper ordering.

uninstall

gitswitch uninstall [--shell <zsh|bash|fish>]

Removes the shell integration block (or oh-my-zsh plugin), unregisters the HTTPS credential helper, and removes the gh wrapper — whichever were installed. Your accounts are left alone. Reload your shell to finish.

doctor

gitswitch doctor [--json]

  ✓  git 2.50.1
  ✓  gh  2.95.0
  ✓  HTTPS pushes routed by gitswitch
  ✓  Session Isolation active (bare `gh` commands resolve per-repo)

The HTTPS check is the interesting one — git asks credential helpers in config order and takes the first answer, so another tool's helper registered ahead of gitswitch means gitswitch never gets asked:

  ✗  HTTPS pushes answered by another helper before gitswitch:
       credential.https://github.com.helper → !/opt/homebrew/bin/gh auth git-credential
       pushes may use the wrong account — run: gitswitch shell

gitswitch shell fixes the order without removing the other helper. See HTTPS Push Routing.

Channels

version

gitswitch version

Prints your version and checks for a newer one (cached 24h).

upgrade

gitswitch upgrade

Installs the latest release. On a Homebrew install it tells you to run brew upgrade gitswitch instead.

beta / stable

gitswitch beta      # canary pre-releases
gitswitch stable    # back to normal

Both confirm first and never touch ~/.config/gitswitch/. See Versions & Release Channels.

Extras

login

gitswitch login [--profile <nickname>] [--host <hostname>]

Delegates to gh auth login (the real GitHub CLI's own login command) to authenticate with GitHub, then reads the resulting account back via gh. Creates an account with your name, email, and username filled in — no custom OAuth app or separate registration step needed since gh owns the account the moment it authenticates. Re-running it on an existing account refreshes your login and keeps your SSH/signing keys. See Connecting Accounts.

skills

gitswitch skills [--scope user|project] [--offline]

Installs the gitswitch skill, embedded in the binary. Tries skills.sh first (works with Claude Code, Cursor, Codex, and more); falls back to installing directly for Claude Code and the shared .agents/skills convention when --offline is passed or npx isn't available. user → ~/.claude/skills/, ~/.agents/skills/ (default), project → .claude/skills/, .agents/skills/.

reauthor

gitswitch reauthor <base> --to <nickname> [--from <email>] [--push] [--yes]

Rewrites author and committer on commits between <base> and HEAD. <base> is a commit-ish or a bare number meaning "the last N commits".

This rewrites history. Full context in AI Coding Agents.

pacman

gitswitch pacman

Toggles arcade mode on or off for every future launch. No, we won't explain it here.

record / recommend

Used by the shell hook. You rarely run these by hand.

gitswitch record    [--path <dir>]    # count the active account for this repo
gitswitch recommend [--path <dir>]    # print the recommended account, if any

recommend exits 0 and prints nickname<TAB>name<TAB>email when there's a recommendation, 1 silently when there isn't. See Pins & Identity Awareness.

Exit codes

gitswitch recommend exiting 1 is normal and expected: it means "nothing to suggest".

Where things are stored

Full detail in Configuration.