Skip to content
$ gitswitch ✦
Nord
★ star

CLI Commands

Interactive TUI

Section titled “Interactive TUI”
Terminal window
gitswitch

Opens the full terminal UI. Navigate profiles, add/edit, switch themes, and manage identities interactively.

Keybindings:

  • ↑ / ↓ or k / j — Navigate profiles
  • enter — Switch to selected profile
  • a — Add new profile
  • e — Edit selected profile
  • ctrl+d (in edit mode) — Delete profile
  • c — Cycle color theme (12 palettes)
  • ? — Show CLI quick reference
  • q — Quit

Quick switch

Section titled “Quick switch”
Terminal window
gitswitch work

Switch immediately to a profile. Useful in scripts or when you know the profile name.

List & Show

Section titled “List & Show”

Show current identity

Section titled “Show current identity”
Terminal window
gitswitch current

Displays the active profile name and email.

List all profiles

Section titled “List all profiles”
Terminal window
gitswitch list

Shows all available profiles with their email addresses.

Profile management

Section titled “Profile management”

Add a profile

Section titled “Add a profile”
Terminal window
gitswitch add NICKNAME USERNAME EMAIL [FLAGS]

Flags:

  • --ssh-key <path> — Path to SSH private key
  • --gpg-key <id> — GPG signing key ID
  • --gh-user <username> — GitHub username for gh auth switch

Example:

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

Edit a profile

Section titled “Edit a profile”
Terminal window
gitswitch edit NICKNAME

Modify an existing profile (TUI).

Remove a profile

Section titled “Remove a profile”
Terminal window
gitswitch remove NICKNAME

Delete a profile permanently.

Repo-specific identity

Section titled “Repo-specific identity”

Pin identity to repo

Section titled “Pin identity to repo”
Terminal window
gitswitch pin NICKNAME

Pin a profile to the current repo. This profile will be recommended (or automatically switched) when you enter this directory.

Unpin identity

Section titled “Unpin identity”
Terminal window
gitswitch unpin

Remove the pin, fall back to auto-recommendation based on usage history.

System commands

Section titled “System commands”

Initialize/reimport git config

Section titled “Initialize/reimport git config”
Terminal window
gitswitch init

Re-imports your current global git config as the default profile. Useful if you’ve manually edited ~/.gitconfig.

Show version

Section titled “Show version”
Terminal window
gitswitch version

Display current version and check for updates.

Upgrade

Section titled “Upgrade”
Terminal window
gitswitch upgrade

Upgrade to the latest release.

Shell integration setup

Section titled “Shell integration setup”
Terminal window
gitswitch install

Sets up:

  • Prompt segment (shows active identity in your shell prompt)
  • Identity nudge (suggests appropriate identity when entering a repo)
  • Tab completion (completes gitswitch commands and profile names)

Detects and configures:

  • Starship → adds [custom.gitswitch] to ~/.config/starship.toml
  • oh-my-zsh → creates plugin at ~/.oh-my-zsh/custom/plugins/gitswitch/
  • Powerlevel10k → prints manual step for ~/.p10k.zsh
  • Raw zsh/bash/fish → appends to rc file

Idempotent — safe to run multiple times.

Help

Section titled “Help”
Terminal window
gitswitch help

Show help text.

Terminal window
gitswitch COMMAND help

Show help for a specific command.

Full syntax reference

Section titled “Full syntax reference”
Terminal window
gitswitch                    # Open TUI
gitswitch PROFILE            # Switch to profile
gitswitch add NICK NAME EMAIL [FLAGS]  # Add profile
gitswitch remove NICK        # Remove profile
gitswitch edit NICK          # Edit profile (TUI)
gitswitch switch NICK        # Switch (explicit command)
gitswitch current            # Show active identity
gitswitch list               # List all profiles
gitswitch pin [NICK]         # Pin profile to repo
gitswitch unpin              # Remove pin
gitswitch init               # Reimport git config
gitswitch install            # Set up shell integration
gitswitch version            # Show version and check updates
gitswitch upgrade            # Upgrade to latest
gitswitch help               # Show help

Exit codes

Section titled “Exit codes”
  • 0 — Success
  • 1 — General error
  • 2 — Profile not found
  • 3 — Invalid input

Environment variables

Section titled “Environment variables”
  • GITSWITCH_CONFIG_DIR — Override config directory (default: ~/.config/gitswitch)