gitkey

Stop editing ~/.ssh/config manually.

gitkey is a CLI for managing SSH keys and Git profiles. It helps you work with multiple GitHub and Bitbucket accounts without manually juggling SSH config, remotes, and agent state.

Contents

• Why
• Features
• Requirements
• Installation
• Usage
• Example
• Zsh Prompt Integration
• Development
• Limitations
• Roadmap
• Contributing

Why

If you use multiple Git accounts across work, personal projects, or different providers, you have probably hit at least one of these:

• Permission denied (publickey)
• the wrong SSH key is being used
• manual edits in ~/.ssh/config
• confusing ssh-agent state

gitkey gives you a small CLI to manage that workflow in one place.

Features

• Manage SSH profiles from ~/.ssh/config
• Clone repositories with profile selection
• Switch the SSH profile used by an existing repo
• Show the active SSH profile for the current repository
• Diagnose SSH setup with doctor
• Auto-fix common permission issues with fix
• Generate new SSH keys
• Add keys to ssh-agent and macOS Keychain
• Open, reveal, copy, and inspect SSH key files
• Install zsh right-prompt integration

Requirements

• Node.js >=20
• git
• OpenSSH tools such as ssh, ssh-add, and ssh-keygen
• zsh if you want prompt integration
• macOS for the best supported experience today

Installation

npm install -g @bagdevich/gitkey

Usage

List SSH profiles:

gitkey list

Clone a repository with a selected SSH profile:

gitkey clone git@github.com:org/repo.git

Switch SSH profile in the current repository:

gitkey use

Switch a specific remote:

gitkey use origin

Show current SSH profile:

gitkey status

Prompt-friendly output:

gitkey status --prompt

Run diagnostics:

gitkey doctor

Fix common SSH issues:

gitkey fix

Add a key to ssh-agent:

gitkey agent-add

Generate a new SSH key:

gitkey generate

Test an SSH connection:

gitkey test

Open a public key file:

gitkey open
gitkey open --current

Open a private key file explicitly:

gitkey open --private

Reveal a key in Finder:

gitkey reveal
gitkey reveal --pub

Reveal a private key in Finder explicitly:

gitkey reveal --private

Copy a public key to clipboard:

gitkey copy-pub
gitkey copy-pub --current

Print a public key:

gitkey show
gitkey show --current

Print a private key explicitly:

gitkey show --private

Example

Given this SSH config:

Host keyName
  HostName github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/keyNamegit
  IdentitiesOnly yes

Instead of:

git clone git@github.com:org/repo.git

You can run:

gitkey clone git@github.com:org/repo.git

Select:

keyName -> github.com ~/.ssh/keyNamegit

And gitkey will execute:

git clone git@keyName:org/repo.git

Zsh Prompt Integration

Install:

gitkey install-shell
source ~/.zshrc

Inside a Git repository, your prompt can show:

🔑 keyName

Development

git clone git@github.com:bagdevich/gitkey.git
cd gitkey

npm install
npm test
npm run dev -- list

Build:

npm run build
npm link
gitkey list

Limitations

• agent-add, generate, install-shell, open, reveal, and copy-pub are currently optimized for macOS.
• Prompt integration currently targets zsh.
• SSH profiles are expected to be defined in ~/.ssh/config.

Roadmap

• convert HTTPS remotes to SSH
• extended repo info
• test all profiles
• prune unused keys
• Windows support

Contributing

Pull requests are welcome.

If you find a bug or have an idea, open an issue.