git-switch-cli 0.1.3

Effortlessly manage multiple Git identities and SSH keys. Generate keys, save per-profile Git name/email, and switch profiles in one command. Auto-updates ~/.ssh include and your global Git config for GitHub/GitLab.

git-switch

Effortlessly manage multiple Git identities and SSH keys. Generate keys, save per-profile Git name/email, and switch profiles in one command. Auto-updates ~/.ssh include and your global Git config for GitHub/GitLab.

Installation

pip install git-switch-cli

Usage

After installing, run:

gswitch

Note: You can also use git-switch, but gswitch is recommended to avoid conflicts with Git's built-in git switch command (see Troubleshooting below).

You should see:

Hello from git-switch 👋

## SSH profiles utility

Manage multiple Git SSH accounts and switch keys quickly.

### Setup

```bash
gswitch ssh init

Version

Print the installed version:

gswitch --version

This creates a managed include at ~/.ssh/git-switch-managed.conf and ensures your ~/.ssh/config includes it.

Add a profile

Generate a new ed25519 key managed by this tool:

gswitch ssh add --name personal --email [e-mail] --generate

If a key already exists at the generated path, either remove it or force overwrite:

gswitch ssh add --name personal --email [e-mail] --generate --force

Or use an existing private key:

gswitch ssh add --name work --key-path ~/.ssh/id_ed25519_work --hosts github.com,gitlab.com

View the public key path printed, and add it to GitHub/GitLab.

List profiles

gswitch ssh list

Activate a profile

gswitch ssh use --name work                  # applies Git identity globally

This updates ~/.ssh/git-switch-managed.conf with the selected key for configured hosts.

Remove a profile

gswitch ssh remove --name personal
# To also delete generated keys (only if under the managed directory):
gswitch ssh remove --name personal --delete-keys --force

Profiles are stored at ~/.config/git-switch/profiles.json. Generated keys live under ~/.ssh/git-switch/<profile>/.

Store Git identity on profile

You can save Git identity per profile during add:

gswitch ssh add --name work --key-path ~/.ssh/id_ed25519_work --git-name "Your Work Name" --git-email [e-mail]

When you run gswitch ssh use, the saved Git identity is applied automatically to your global Git config.

Update a profile's Git identity

gswitch ssh update --name personal --git-name "New Name" --git-email [e-mail]

Then apply it:

gswitch ssh use --name personal

Copy a profile's public key

Copy a profile's public key to your clipboard for adding to GitHub/GitLab:

gswitch copy-key personal   # copy 'personal' profile's public key
gswitch copy-key            # copy the active profile's public key

This uses your OS clipboard tool (pbcopy on macOS, wl-copy/xclip on Linux, clip on Windows). If unavailable, the key is printed to stdout.

HTTPS (PAT) profiles utility

Manage Git over HTTPS using Personal Access Tokens stored via Git's credential helper.

Add a PAT profile

Provide your token via stdin (recommended):

printf "%s" "$GITHUB_TOKEN" | git-switch pat add \
  --name work-https \
  --username your-username \
  --hosts github.com \
  --token-stdin \
  --git-name "Your Work Name" \
  --git-email [e-mail]

Or pass it directly:

git-switch pat add --name personal-https --username your-username --hosts github.com \
  --token "$GITHUB_TOKEN"

This stores the token in your configured Git credential helper (e.g., osxkeychain/libsecret/manager-core).

List and activate PAT profiles

git-switch pat list
git-switch pat use --name work-https

Note: PAT auth works with HTTPS remotes. Convert SSH remotes as needed:

git remote set-url origin https://github.com/<owner>/<repo>.git

Remove a PAT profile

git-switch pat remove --name work-https

This also erases saved credentials for its hosts via the credential helper.

Development

Makefile commands

• Install: creates/uses a virtual environment and installs the package in editable mode

make install
# If no venv was active, this will drop you into an interactive shell
# with the venv activated. Exit with Ctrl-D when done.
# To skip opening a shell (CI usage):
# NO_SHELL=1 make install

• Shell in venv: launches a subshell with the venv activated

make shell
# Exit with Ctrl-D when done

• Build: builds sdist and wheel into dist/

make build

• Test with coverage: runs the full test suite and generates terminal + HTML coverage (htmlcov/index.html)

make test

• Test an individual file or test: pass FILE to run a specific test file or node id

make test-file FILE=tests/test_cli.py
make test-file FILE=tests/test_cli.py::test_handle_copy_key_fallback_prints_key

Troubleshooting

Command not found or wrong command runs (especially with oh-my-zsh)

The command git-switch can conflict with Git's built-in git switch command (introduced in Git 2.23). This is particularly common with:

• oh-my-zsh with the git plugin enabled
• Shells with git aliases or autocomplete features
• Zsh command correction features

Solution 1: Use gswitch instead (recommended)

We provide an alias gswitch that avoids the conflict entirely:

gswitch ssh list
gswitch ssh use --name personal

Solution 2: Ensure PATH includes pip's bin directory

When installing from PyPI, the executable is placed in Python's bin directory. Make sure it's in your PATH:

# Check if the command exists and where
which gswitch
which git-switch

# If not found, add to your ~/.zshrc or ~/.bashrc:
export PATH="$HOME/.local/bin:$PATH"

# Then reload your shell
source ~/.zshrc

Solution 3: Use the full path

# Find where it's installed
python -m pip show -f git-switch-cli | grep -E "^Location:|bin/gswitch"

# Run with full path
~/.local/bin/gswitch ssh list

Solution 4: Install with pipx (isolated environment)

pipx install git-switch-cli
# pipx automatically adds its bin directory to PATH

Verify installation

gswitch --version
# Should print: 0.1.3 (or current version)