github-archiver

GitHub Archiver CLI

A powerful CLI for mass archiving GitHub repositories with parallel processing and comprehensive error handling.

Features

• ✨ Mass Archive - Archive multiple repositories in parallel
• 🔐 Secure Auth - Token stored locally at ~/.github-archiver/config.json
• ⚡ Parallel Processing - Configurable concurrency (1-50)
• 📋 Flexible Input - Load repos from editor, file, or stdin
• 🔍 Validation - Dry-run mode to validate without archiving
• 📊 Progress Tracking - Real-time progress bars and ETA
• 🛡️ Error Recovery - Comprehensive error handling with helpful guidance
• 📝 Detailed Logging - Structured logging to files and console

Installation

npm install -g github-archiver

or with Bun:

bun install -g github-archiver

From Source

git clone https://github.com/mynameistito/github-archiver.git
cd github-archiver
bun install && bun run build
bun install -g .

Development

bun install
bun run dev -- <command>

Note: This project is optimized for Bun. While it works with Node.js (v22+), Bun provides faster installation, execution, and development experience.

Quick Start

# Authenticate
github-archiver auth login

# Archive (opens editor to input repos)
github-archiver archive

Commands

auth

Manage GitHub authentication.

Command	Description
auth login	Authenticate with Personal Access Token
auth logout	Remove stored token
auth status	Check authentication status

archive

Archive multiple repositories.

github-archiver archive [options]

Option	Default	Description
--file <path>	-	Read repository URLs from file
--stdin	-	Read from stdin
--dry-run	false	Validate without archiving
--concurrency <n>	3	Parallel operations (1-50)
--timeout <n>	300	API timeout in seconds (10-3600)
--verbose	false	Enable verbose logging
--force	false	Skip confirmation prompts

Examples:

# Interactive (opens editor)
github-archiver archive

# From file
github-archiver archive --file repos.txt

# From stdin
cat repos.txt | github-archiver archive --stdin

# Dry-run
github-archiver archive --file repos.txt --dry-run

# High concurrency
github-archiver archive --file repos.txt --concurrency 10

# Force without confirmation
github-archiver archive --file repos.txt --force

Input Format

Supported formats:

• HTTPS: https://github.com/owner/repo or https://github.com/owner/repo.git
• SSH: [e-mail]:owner/repo.git or [e-mail]:owner/repo
• Shorthand: owner/repo

File Example:

# Repositories to archive
https://github.com/facebook/react
torvalds/linux
owner/private-repo

# Comments ignored
https://github.com/nodejs/node

GitHub Token Requirements

• Scope: repo (Full control of private repositories)
• Minimum Permissions: Push access to target repositories

Generate token: https://github.com/settings/tokens/new → Create with repo scope → Run github-archiver auth login

Output Example

🔐 Checking authentication...
✅ Authenticated as: username

📝 Getting repositories...
📋 Will archive 5 repositories:
   1. facebook/react
   2. torvalds/linux
   3. owner/repo-1
   4. owner/repo-2
   5. owner/repo-3

Are you sure you want to archive these repositories? [y/N]: y

Starting to archive repositories... (concurrency: 3)

[=======================     ] 4/5 (80%) - owner/repo-3

┌────────────────────────────────────┐
│  Archive Operation Summary         │
├────────────────────────────────────┤
│ Successful: 5                      │
│ Skipped:    0                      │
│ Failed:     0                      │
├────────────────────────────────────┤
│ Total:      5                      │
│ Duration:   2m 45s                 │
└────────────────────────────────────┘

✅ All repositories processed successfully!

Troubleshooting

Authentication

No token found: Run github-archiver auth login

Invalid/expired token: Generate new token at https://github.com/settings/tokens → auth logout → auth login

Permissions

Permission denied: Verify repo ownership/push access, check repo scope, ensure repo isn't already archived

Rate Limiting

Rate limit exceeded: Wait (resets hourly), lower --concurrency 1, increase --timeout 600

Network

Network error/timeout: Check connection, GitHub API may be unavailable, retry with --timeout 600

Repository Not Found

Repository not found: Verify URL, check if deleted, confirm GitHub access

Configuration

Config: ~/.github-archiver/config.json (Linux/macOS) or %USERPROFILE%\.github-archiver\config.json (Windows)

Logs: ~/.github-archiver/logs/ (Linux/macOS) or %USERPROFILE%\.github-archiver\logs\ (Windows)

Architecture

src/
├── commands/      # CLI commands (auth, archive)
├── services/      # GitHub API, archiving, auth management
├── utils/         # Parsing, formatting, logging
├── types/         # TypeScript definitions
└── constants/     # Configuration constants

tests/
└── unit/          # Unit tests

Core Services:

• GitHubService: GitHub API interactions with retry logic
• Archiver: Parallel archiving with p-queue
• AuthManager: Secure token storage
• InputHandler: Input from editor, file, or stdin
• ProgressDisplay: Progress bar and summary output

Development

bun install

# Development commands
bun run typecheck    # Check TypeScript
bun run test         # Run unit tests
bun run test:coverage  # Run tests with coverage
bun run build        # Build production bundle
bun run lint         # Check code style
bun run format       # Auto-format code
bun run dev -- auth login  # Run dev mode

Using npm instead?

npm install
npm run typecheck    # Equivalent commands
npm run test
npm run build
npm run lint
npm run format

Code Standards

This project uses Ultracite (Biome) for:

• Strict TypeScript (no implicit any)
• Accessibility, performance, security best practices
• Consistent formatting
• Comprehensive error handling

Run code quality checks:

# Check for issues
bun run lint

# Auto-fix and format code
bun run format

See AGENTS.md for detailed code standards and best practices.

Release Process

This project uses semantic-release for automated versioning and publishing.

Commit format (Conventional Commits):

• feat: → minor bump
• fix: → patch bump
• BREAKING CHANGE: → major bump
• chore:, docs:, test: → no bump

Pushing to main triggers automatic release. See docs/RELEASE.md for detailed setup and workflow.

Contributing

• Install dependencies: bun install
• Follow code standards: bun run format
• Add tests for new features
• Ensure bun run typecheck and bun run test pass
• Create pull request with clear description

Before committing:

bun run format    # Auto-fix code style
bun run lint      # Check for issues
bun run typecheck # Verify TypeScript
bun run test      # Run test suite
bun run build     # Build production bundle

License

MIT - See LICENSE file for details.

Support

Check the Troubleshooting section or open an issue on GitHub.

Runtime & Tooling

• Runtime: Bun (primary) or Node.js 22+
• Package Manager: Bun (recommended) or npm
• Language: TypeScript
• CLI Framework: Commander.js
• GitHub API: Octokit
• Logging: Winston
• Code Quality: Biome (via Ultracite preset)
• Task Queue: p-queue
• Release Management: Changesets

Acknowledgments

Built with TypeScript, Commander.js, Octokit, Winston, Biome, and optimized for Bun runtime.

Releases