GithubRepoRemover/README.md

# GitHub Repository Remover

A CLI tool for bulk-deleting GitHub repositories with an interactive interface. Built with .NET 9 and Spectre.Console for a clean terminal experience.

## What it does

- Interactive repository selection with a clean multi-select interface
- Secure authentication using GitHub Personal Access Tokens
- Batch deletion of multiple repositories
- Multiple confirmation prompts to prevent accidents
- Real-time progress feedback
- Handles GitHub API rate limits gracefully

## Installation

### Download and run (recommended)

No .NET installation required! Just download the executable for your platform:

1. Head to the [Releases](https://github.com/mtfarkas/GithubRepoRemover/releases) page
2. Download the right file for your system:
   - **Windows**: `github-repo-remover-win-x64.exe`
   - **macOS**: `github-repo-remover-osx-x64` (Intel) or `github-repo-remover-osx-arm64` (Apple Silicon)
   - **Linux**: `github-repo-remover-linux-x64`
3. On macOS/Linux, make it executable: `chmod +x github-repo-remover-*`
4. Run it!

### Build it yourself

Need .NET 9.0 SDK installed:

```bash
git clone https://github.com/mtfarkas/GithubRepoRemover.git
cd GithubRepoRemover
dotnet build -c Release
```

## How to use it

### Basic usage

```bash
github-repo-remover --token YOUR_GITHUB_TOKEN
```

| Option | Short | What it does | Required |
|--------|-------|-------------|----------|
| `--token` | `-t` | Your GitHub Personal Access Token | Yes |

### Example

```bash
github-repo-remover --token ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Here's what happens when you run it:
1. Authenticates with GitHub using your token
2. Fetches all your repositories
3. Shows you an interactive list to choose from
4. Displays your selected repos for review
5. Asks for confirmation (twice!)
6. Deletes the selected repositories with progress updates

## Setting up your GitHub token

You'll need a GitHub Personal Access Token with the right permissions.

### Creating the token

1. **Go to GitHub Settings**
   - Visit [GitHub.com](https://github.com)
   - Click your profile picture → **Settings**

2. **Navigate to Developer Settings**
   - Scroll down and click **Developer settings**
   - Click **Personal access tokens** → **Tokens (classic)**

3. **Create a new token**
   - Click **Generate new token** → **Generate new token (classic)**
   - Give it a name like "GitHub Repo Remover CLI"

4. **Set expiration**
   - Pick an expiration date that makes sense
   - Avoid "No expiration" unless you really need it

5. **Choose the right permissions**
   
   **Important:** Your token needs these scopes:
   
   - ✅ **`repo`** - Full control of private repositories
   - ✅ **`delete_repo`** - Delete repositories
   
   Without both of these, the tool won't work. The `repo` scope lets it read your repository list, and `delete_repo` does what it says on the tin.

6. **Generate and save the token**
   - Click **Generate token**
   - **Copy it immediately** - GitHub won't show it again!
   - Store it somewhere safe (password manager recommended)

### Token security tips

- Never commit tokens to git repositories
- Use a password manager to store them
- Set reasonable expiration dates
- Revoke tokens when you're done with them
- Consider using environment variables for scripts

### Using environment variables

If you don't want to type the token every time:

```bash
# Windows (PowerShell)
$env:GITHUB_TOKEN = "your_token_here"
github-repo-remover --token $env:GITHUB_TOKEN

# Linux/macOS
export GITHUB_TOKEN="your_token_here"
github-repo-remover --token $GITHUB_TOKEN
```

## Safety features

This tool tries really hard not to let you accidentally delete things:

- Two separate confirmation prompts before any deletion
- Shows you exactly which repositories will be deleted
- You have to manually select each repository
- Real-time feedback so you know what's happening

## Error handling

The tool handles common problems gracefully:
- Invalid or expired tokens get clear error messages
- GitHub rate limiting is handled automatically
- Network problems are reported clearly
- Missing permissions get specific guidance

## Building from source

```bash
git clone https://github.com/mtfarkas/GithubRepoRemover.git
cd GithubRepoRemover
dotnet restore
dotnet build -c Release

# To run it
dotnet run --project src/GithubRepoRemover -- --token YOUR_TOKEN
```

## Contributing

Pull requests welcome! For big changes, please open an issue first so we can discuss it.

### Development setup

You'll need .NET 9.0 SDK installed, then:

1. Clone the repo
2. Run `dotnet restore`
3. Start hacking!

### Building release executables

To build the self-contained executables:

```bash
# Windows
dotnet publish -c Release -r win-x64 --self-contained -p:PublishSingleFile=true

# macOS Intel
dotnet publish -c Release -r osx-x64 --self-contained -p:PublishSingleFile=true

# macOS Apple Silicon
dotnet publish -c Release -r osx-arm64 --self-contained -p:PublishSingleFile=true

# Linux
dotnet publish -c Release -r linux-x64 --self-contained -p:PublishSingleFile=true
```

Executables end up in `src/GithubRepoRemover/bin/Release/net9.0/{runtime}/publish/`

## License

MIT License

## Important warning

**This tool permanently deletes GitHub repositories.** Once they're gone, they're gone (unless you have backups). Make sure you know what you're doing and have backups of anything important.

I'm not responsible if you accidentally delete something you needed.

## Getting help

Run into problems or have ideas?
- [Open an issue](https://github.com/mtfarkas/GithubRepoRemover/issues) for bugs or feature requests
- [Start a discussion](https://github.com/mtfarkas/GithubRepoRemover/discussions) for questions

---

Made with ❤️ by [mtfarkas](https://github.com/mtfarkas)