Github Folder Downloader

A zero-config CLI tool to download specific folders from a GitHub repository — without cloning the whole repo.

Use the online web version here, https://download-folder.github.io/

✨ Features

• Download any subfolder from a GitHub repository ZIP
• Supports both full GitHub URLs and shorthand syntax (owner/repo[#branch])
• Specify a custom target directory
• Automatically detects the default branch if none is specified
• Real-time file extraction progress with elegant terminal UI
• Safety checks to prevent accidental file overwrites
• Graceful error handling and cleanup
• Works with npx — no install required

📦 Installation

Global

npm install -g folder-downloader@latest

Local

npm install folder-downloader@latest

Temporary via npx

npx folder-downloader@latest metallicjs/templates saas-lite

🚀 Usage

folder-downloader <repo> <subfolder> [target-folder]

You can use either of the following for :

• Full GitHub URL (e.g. https://github.com/user/repo)

• Shorthand syntax (e.g. user/repo or user/repo#branch)

Arguments

| Argument | Description | | ----------------- | ------------------------------------------------------------------ | | <repo> | GitHub repository in full URL or shorthand (owner/repo[#branch]) | | <subfolder> | Subdirectory path in the repo to extract | | [target-folder] | Optional: Where to save locally (defaults to subfolder name) |

📘 Examples

Download from default branch using shorthand

npx folder-downloader@latest metallicjs/templates saas-lite

Download using full GitHub URL

npx folder-downloader@latest https://github.com/metallicjs/templates saas-lite

Download from a specific branch

npx folder-downloader@latest metallicjs/templates#main saas-lite

Download to a custom folder

npx folder-downloader@latest metallicjs/templates saas-lite my-app-folder

⚙️ How It Works

1. Parses the repo input and identifies the branch (or fetches the default)

2. Downloads the ZIP archive of the branch

3. Extracts only the specified folder

4. Writes extracted files to the chosen output directory

5. Provides real-time file count and progress updates

🛡️ Safety Features

1. Prevents overwriting existing files or folders

2. Detects and blocks extraction if target is a non-empty directory

3. Cleans up temporary files on failure

4. Counts and reports total extracted files

5. Detailed error messages for bad URLs or missing folders

🔧 Technical Details

Dependencies

• chalk: Colorful console output

• fs-extra: File system utilities

• node-fetch: HTTP requests

• ora: Terminal spinners

• unzipper: ZIP file streaming

Dev Dependencies

• TypeScript

• tsup (bundler)

• ts-node (for development)

🛠 Development

Clone this repo

git clone https://github.com/yourusername/folder-downloader.git

Install deps

npm install

Scripts

npm run build – Build the project

npm run dev – Watch + build on changes

npm run prepublishOnly – Build before publish

📄 License

ISC

👤 Author

Kehinde Oke