gitload 🦦

A beautiful CLI to download files, folders, or entire repositories from GitHub URLs.

Installation

npm install -g gitload-cli

Or run directly with npx:

npx gitload-cli <github-url>

Usage

gitload <url> [options]

Arguments:
  url                    GitHub URL (repo root, folder, or file)

Options:
  -z, --zip <path>       Save as ZIP file at the specified path
  -o, --output <dir>     Output directory (default: folder named after URL path)
  -t, --token <token>    GitHub personal access token (for private repos)
  --gh                   Use token from gh CLI (requires gh auth login)
  --no-color             Disable colored output
  -V, --version          Output version number
  -h, --help             Display help

Examples

Download an entire repository

gitload https://github.com/user/repo
# Creates ./repo/ folder

Download a specific folder

gitload https://github.com/user/repo/tree/main/src
# Creates ./src/ folder

Download a single file

gitload https://github.com/user/repo/blob/main/README.md
# Creates ./README.md

Download as a ZIP file

gitload https://github.com/user/repo -z ./repo.zip

Download to a custom directory

gitload https://github.com/user/repo/tree/main/src -o ./my-source
# Creates ./my-source/ folder

Download contents flat to current directory

gitload https://github.com/user/repo/tree/main/src -o .
# Downloads directly to current folder

Download a private repository

# Using gh CLI (if you have gh installed and logged in)
gitload https://github.com/user/private-repo --gh

# Using the --token flag
gitload https://github.com/user/private-repo --token ghp_xxxx

# Or using the GITHUB_TOKEN environment variable
export GITHUB_TOKEN=ghp_xxxx
gitload https://github.com/user/private-repo

Authentication

Token priority (highest to lowest):

1. --token flag
2. GITHUB_TOKEN environment variable
3. --gh flag (uses gh auth token)

Features

• 📁 Download entire repositories, folders, or single files
• 🗜️ Create ZIP archives with the --zip option
• 🎨 Beautiful progress display with colors and progress bars
• 🔐 Support for private repositories via GitHub tokens
• ⚡ Efficient file discovery using GitHub's Git Trees API

Environment Variables

| Variable | Description | |----------|-------------| | GITHUB_TOKEN | GitHub personal access token (alternative to --token) |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Runtime error (network, file system, etc.) | | 2 | Invalid usage (bad URL, missing arguments) |

License

MIT