gh-ssh
An interactive CLI that guides you through creating or reusing an SSH key and connecting it to GitHub in a 7-step workflow. Supports macOS and Linux with clipboard integration.
Installation
Requirements:
- Node.js >= 20
Install globally:
- npm install -g gh-ssh
Run without installing:
- npx gh-ssh
Usage
Run interactive setup:
- gh-ssh
Show help/version:
- gh-ssh --help
- gh-ssh --version
Provide options up front:
- gh-ssh --email you@example.com
- gh-ssh --type ed25519
- gh-ssh --key-name id_github_work
- gh-ssh --update-config
- gh-ssh --skip-config
- gh-ssh --upload
- gh-ssh --skip-upload
- gh-ssh --key-title "My MacBook (work)"
Options:
- -h, --help
- -v, --version
- --email GitHub email for key comment
- --type Key type (default: ed25519)
- --key-name Key filename in ~/.ssh (default: id_ed25519 or id_rsa)
- --update-config Update ~/.ssh/config with the selected key
- --skip-config Skip updating ~/.ssh/config
- --upload Upload the public key to GitHub via gh (errors if not possible)
- --skip-upload Skip uploading via gh and show the manual flow
- --key-title </code> Title to use when uploading via gh</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">How it works</h2></p><p class="my-3">1. Detect existing public keys in ~/.ssh and optionally reuse one.<br />2. Generate a new key pair if needed (ed25519 by default, rsa 4096 fallback).<br />3. Start ssh-agent if it is not already running.<br />4. Add the selected key to ssh-agent.<br />5. Optionally update ~/.ssh/config (with an optional GitHub host alias).<br />6. Copy the public key to clipboard (macOS/Linux) or print it to the terminal, then add it at <a href="https://github.com/settings/keys" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">GitHub Settings</a>.<br />7. Prompt to verify with <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">ssh -T git@github.com</code> (or your alias).</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Platform notes</h2></p><p class="my-3">- macOS: full workflow, clipboard uses <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">pbcopy</code>.<br />- Linux: full workflow, clipboard uses <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">wl-copy</code>, <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">xclip</code>, or <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">xsel</code> (if available).<br />- Requires <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">ssh-keygen</code>, <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">ssh-agent</code>, and <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">ssh-add</code> to be available in PATH.</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Development</h2></p><p class="my-3">- Install dependencies: <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">npm install</code><br />- Run locally (TypeScript): <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">npm run dev</code><br />- Type check: <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">npm run typecheck</code><br />- Build CLI: <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">npm run build</code><br />- Run built CLI: <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">npm start</code></p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Manual testing</h2></p><p class="my-3">- <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">npm run dev -- --help</code><br />- <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">npm run dev -- --version</code><br />- <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">npm run dev -- --email test@example.com --type ed25519</code></p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Conventional Commits</h2></p><p class="my-3">We use Conventional Commit–style PR titles and squash merges to drive automated versioning and changelogs. Always use a semantic PR title and squash-merge so the PR title becomes the commit message used for releases.</p><p class="my-3">Examples:</p><p class="my-3">- <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">feat: add support for multiple GitHub hosts</code><br />- <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">fix: handle missing ssh-agent</code><br />- <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">feat!: change default key type</code> (breaking change)<br />- <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">chore: update dev dependencies</code> (no release)<br /></p></div><div class="flex justify-center absolute inset-x-0 bottom-0 bg-gradient-to-t from-background via-background to-transparent pb-4 pt-16"><button data-slot="button" class="inline-flex items-center justify-center whitespace-nowrap text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50 h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down mr-1 h-4 w-4"><path d="m6 9 6 6 6-6"></path></svg>Show more</button></div></div></div><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-dependencies" hidden="" id="radix-_R_aav5ubrb_-content-dependencies" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div><template id="P:3"></template></div></div></div><script>self.__next_f.push([1,"2b:[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}]\n2c:[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^9.39.2\"}]\n2d:[\"$\",\"$L5\",\"husky\",{\"href\":\"/package/husky\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"husky\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^9.1.7\"}]]}]\n2e:[\"$\",\"$L5\",\"prettier\",{\"href\":\"/package/prettier\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"prettier\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^3.8.1\"}]]}]\n2f:[\"$\",\"$L5\",\"tsx\",{\"href\":\"/package/tsx\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"tsx\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^4.7.0\"}]]}]\n30:[\"$\",\"$L5\",\"typescript\",{\"href\":\"/package/typescript\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"typescript\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^5.9.3\"}]]}]\n31:[\"$\",\"$L5\",\"typescript-eslint\",{\"href\":\"/package/typescript-eslint\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity"])</script><script>self.__next_f.push([1," group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"typescript-eslint\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^8.54.0\"}]]}]\n32:[\"$\",\"$L5\",\"vite\",{\"href\":\"/package/vite\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"vite\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^7.3.1\"}]]}]\n33:[\"$\",\"$L5\",\"vitest\",{\"href\":\"/package/vitest\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"vitest\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^4.0.18\"}]]}]\n"])</script><div hidden id="S:3"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-versions" hidden="" id="radix-_R_aav5ubrb_-content-versions" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS=function(a,b){a=document.getElementById(a);b=document.getElementById(b);for(a.parentNode.removeChild(a);a.firstChild;)b.parentNode.insertBefore(a.firstChild,b);b.parentNode.removeChild(b)};$RS("S:3","P:3")</script><script>$RC("B:1","S:1")</script></body></html>