Metadata-Version: 2.4
Name: gh-ssh-setup
Version: 0.1.0
Summary: Generate an SSH key and add it to GitHub — with clear steps, or fully automated via the GitHub API.
Author-email: Rajat Ghosh <rajat.ghosh11@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/rghosh08/gh-ssh-setup
Project-URL: Issues, https://github.com/rghosh08/gh-ssh-setup/issues
Keywords: ssh,github,ssh-key,ed25519,automation,devops
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=3.4
Requires-Dist: bcrypt>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# gh-ssh-setup

Generate an SSH key on your machine and add it to GitHub — either with clear,
copy-paste steps, or **fully automated** through the GitHub REST API.

- 🔐 Pure-Python key generation (Ed25519 by default, RSA optional) via
  [`cryptography`](https://cryptography.io) — no external `ssh-keygen` required.
- 📋 Prints every manual step (ssh-agent, copy public key, add on GitHub, test).
- 🤖 One command to generate + upload + verify, end to end.
- 🛡️ Private key written `0600`; only the *public* key ever leaves your machine.

## Install

```bash
pip install gh-ssh-setup
```

From source:

```bash
git clone https://github.com/rghosh08/gh-ssh-setup
cd gh-ssh-setup
pip install -e .
```

## Usage

### 1. Generate a key and see the manual GitHub steps

```bash
gh-ssh-setup generate --email you@example.com
```

This creates `~/.ssh/id_ed25519` + `~/.ssh/id_ed25519.pub` and prints the exact
steps to register it at <https://github.com/settings/ssh/new>.

### 2. Full automation (generate → upload → test)

Create a GitHub **Personal Access Token** with the `admin:public_key`
(*write:public_key*) scope at <https://github.com/settings/tokens>, then:

```bash
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxx
gh-ssh-setup setup --email you@example.com --title "my-laptop"
```

Output:

```
✔ Authenticated to GitHub as yourname
✔ Generated ed25519 key
✔ Added key 'my-laptop' to GitHub (id=123456789)
→ Testing: ssh -T git@github.com
  Hi yourname! You've successfully authenticated, but GitHub does not provide shell access.
```

### Other commands

```bash
gh-ssh-setup upload --key-path ~/.ssh/id_ed25519.pub --title "existing-key"
gh-ssh-setup list        # show keys already on your GitHub account
gh-ssh-setup test        # run ssh -T git@github.com
```

Run `gh-ssh-setup <command> --help` for all flags (`--type rsa`, `--passphrase`,
`--overwrite`, `--key-path`, `--no-agent`, ...). `setup`/`generate` also print an
optional `~/.ssh/config` block and load the key into ssh-agent for you (skip with
`--no-agent`).

## Use as a library

```python
from gh_ssh_setup import generate_key_pair, upload_key_to_github, manual_steps

kp = generate_key_pair(comment="you@example.com")
print(manual_steps(kp))                              # copy-paste steps
upload_key_to_github(kp.public_key, title="laptop")  # or automate it
```

## GitHub MCP (agentic automation)

If you drive this from an agent that has the **GitHub MCP server** connected,
you can skip the token plumbing and let the agent call the equivalent MCP tool
to create the key (`POST /user/keys`). This package still does the key
*generation* locally (the private key must never leave your machine); the MCP
only handles the public-key upload. Point your agent at:

- Generate locally: `gh-ssh-setup generate` (or `generate_key_pair()`).
- Upload via MCP: call the GitHub MCP "create SSH signing/auth key" tool with
  the `.pub` contents, or just use `gh-ssh-setup setup` with a token.

## Security notes

- The **private** key (`id_ed25519`) is secret. This tool writes it `0600` and
  never transmits it. Only the `.pub` file is uploaded.
- Prefer a short-lived, minimally-scoped PAT (`admin:public_key` only).
- Consider a `--passphrase` for defense in depth on shared machines.

## Development

A `Makefile` wraps the common tasks (`make help` to list them):

```bash
make dev      # pip install -e ".[dev]"
make test     # pytest
make build    # sdist + wheel into dist/
make check    # twine check dist/*
```

CI runs on every push/PR (Python 3.8–3.12). Pushing a `vX.Y.Z` tag publishes to
PyPI automatically via Trusted Publishing — see [PUBLISHING.md](PUBLISHING.md).

## License

MIT — see [LICENSE](LICENSE).
