A wrong SSH key upload or a careless deletion can lock you out of GitHub in seconds: gh ssh-key handles both, carefully. You will use GitHub CLI to inspect the SSH keys on your account, add a public key as either an authentication or signing key, and remove an obsolete key only after checking its numeric ID. Allow about ten minutes if the key already exists on this machine, or longer if you still need to create one. These commands change your GitHub account, but none of them need sudo.
This guide describes GitHub CLI 2.87.3, installed on the machine used for these examples. You need a working gh login with permission to manage your own SSH keys and network access to GitHub. The commands operate on the account selected by your current GitHub CLI authentication, so check that account before changing anything.
Start with read-only checks. They show which executable will run and which GitHub account is active:
$ command -v gh
/usr/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh auth status
The last command prints the authenticated host and account, plus authentication details that vary by machine. Confirm the account before proceeding. If it says you are not logged in, run your normal gh auth login process and return to this checkpoint. Never paste an access token into a shell command or an article example.
Checkpoint: you know the account that will be changed, gh auth status succeeds, and gh ssh-key --help lists add, delete and list.
Ask GitHub CLI for the account's current keys:
$ gh ssh-key list
The installed command prints the keys known to the account. Exact columns and rows depend on your account, so do not script against an example layout copied from somewhere else. Look for the title, key type and numeric ID of each credential: the ID is the value gh ssh-key delete needs.
An empty result is useful: it means there is no key for this account to remove, not that you should guess an ID. If the command fails, check gh auth status, network access and the selected GitHub host before trying a write operation.
Checkpoint: record the exact account and, if you plan to remove a key, copy its numeric ID from this fresh listing. Do not use a line number, fingerprint or title in place of the ID.
gh ssh-key add takes an optional key-file argument, and it uploads the public key you name, not a private key. If you already have one, inspect its file without printing the private half:
$ ls -l "$HOME/.ssh/id_ed25519.pub"
$ head -c 80 "$HOME/.ssh/id_ed25519.pub"; printf '\n'
ssh-ed25519 AAAA... workstation-2026
Use the matching .pub file. Never give gh ssh-key add a private key such as id_ed25519, id_rsa or any file holding an unencrypted private key. If you need a new key, create it with your usual ssh-keygen procedure and protect the private file with a passphrase; key generation sits outside gh ssh-key, and none of this is a reason to delete an existing key.
The command normally runs as your ordinary user. Reach for sudo only if your chosen public-key file is genuinely unreadable by that user, and prefer copying the public file to a user-owned location instead: elevated local privileges do not grant GitHub account access.
Give the key a title that identifies its device or purpose. The title is metadata for you, not a secret:
$ gh ssh-key add "$HOME/.ssh/id_ed25519.pub" \
--title "workstation-2026" \
--type authentication
authentication is the installed default, so the explicit option is not required, but keeping it in a reviewed command makes the intended use clear. GitHub CLI sends the key to the authenticated account and returns an error if the upload fails. Verify a successful add by listing the keys again:
$ gh ssh-key list
Find the new title and confirm its type is authentication. If the add command fails, do not retry blindly before checking whether the key was actually created remotely: a duplicate-key response or a newly visible row means the first attempt may already have worked.
GitHub distinguishes a key used to authenticate Git operations from one used to sign commits or tags. If this public key is for signing, specify the other supported type:
$ gh ssh-key add "$HOME/.ssh/id_ed25519_signing.pub" \
--title "workstation-signing-2026" \
--type signing
The key type does not configure Git signing on the workstation by itself: you still need Git and your signing workflow to use the matching private key. Check the new row with gh ssh-key list before touching Git configuration.
Do not upload the same public key under a different title just to tidy up the listing. Keep one account entry per intended use, and keep the private key secure. If you are not sure whether a key is for authentication or signing, stop and work that out before uploading it.
Warning: deletion is a remote account change. It can immediately stop a device, automation job or signing workflow from using that credential. Before deleting, make sure another working authentication method exists and that the target ID still refers to the old key:
$ gh ssh-key list
$ gh ssh-key delete 12345678
Without --yes, the command asks for confirmation, which is the safer default: read the prompt and cancel if the title or ID is not the key you meant. Use --yes only in a reviewed, non-interactive script where the ID was obtained and checked safely:
$ gh ssh-key delete 12345678 --yes
Recovery: there is no undo flag. Recovery means adding the public key again with gh ssh-key add, provided you still have the correct public key and the account allows it. If you delete the only key needed to access a system, use another GitHub login method or an already-authorised administrator to restore access. Keeping the private key intact does not depend on the GitHub registration: deleting the registration does not destroy local key files.
Unauthenticated or wrong account: run gh auth status and pick the intended account before listing or changing keys. A successful command against the wrong account is still a mistake.
Key file not found: run ls -l -- "$HOME/.ssh/id_ed25519.pub" with the actual path. Check the suffix and spelling, and do not substitute the private file just because its name looks similar.
Duplicate key: list the account's keys and search for the title or fingerprint. A public key registered elsewhere may need removing from the old account or replacing with a freshly generated key, depending on ownership and access requirements.
Delete target unclear: stop. Re-run gh ssh-key list; never guess an ID or use --yes as a way around uncertainty. If the list looks stale, resolve authentication or network errors first.
For the exact installed syntax, use the local help pages:
$ gh ssh-key add --help
$ gh ssh-key delete --help
$ gh ssh-key list --help
gh auth status before changing anything.