gh-download is a Python command-line tool that allows you to download files from GitHub repositories, including private ones, by leveraging your existing gh (GitHub CLI) authentication.
Tip
If using uv, just run:
uvx dotbins get cli/cli --name ghto install the GitHub CLI.uvx gh-download --helpto see the help message.
[ToC] 📚
- Download files from public and private GitHub repositories.
- Utilizes your authenticated
ghCLI session to access private repositories. - Automatically prompts for
gh auth loginif you are not authenticated. - Provides clear, user-friendly output and error messages using the Rich library.
- Simple command-line interface.
- Python: Version 3.11 or higher.
- GitHub CLI (
gh): Must be installed and in your system's PATH. You can install it from https://cli.github.com/ or use dotbins and runuvx dotbins get cli/cli --name ghto install it.
Install gh-download using pip:
pip install gh-downloadOr for development:
-
Clone the repository:
git clone git@github.com:basnijholt/gh-download.git cd gh-download -
Install in development mode:
uv sync source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
After installation, you can use the gh-download command:
gh-download REPO_OWNER REPO_NAME FILE_PATH [OPTIONS]See the output of gh-download -h
Usage: gh-download [OPTIONS] REPO_OWNER REPO_NAME FILE_PATH
Download a specific file from a GitHub repository.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * repo_owner TEXT The owner of the repository (e.g., 'octocat'). │
│ [default: None] │
│ [required] │
│ * repo_name TEXT The name of the repository (e.g., 'Spoon-Knife'). │
│ [default: None] │
│ [required] │
│ * file_path TEXT The path to the file or folder within the │
│ repository (e.g., 'README.md' or │
│ 'src/my_folder'). │
│ [default: None] │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --branch -b TEXT The branch, tag, or commit SHA to download from. │
│ [default: main] │
│ --output -o TEXT Local path to save the downloaded file or folder. If │
│ downloading a file, this can be a new filename or a │
│ directory. If downloading a folder, this is the │
│ directory where the folder will be placed. Defaults │
│ to the original filename/foldername in the current │
│ directory. │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
# Download a file from a public repository
gh-download octocat Spoon-Knife README.md
# Download from a specific branch
gh-download octocat Spoon-Knife README.md --branch main
# Save to a specific location
gh-download octocat Spoon-Knife README.md --output ./my_readme.md
# Download from a different branch
gh-download microsoft vscode package.json --branch release/1.85REPO_OWNER: The owner of the repository (e.g., 'octocat')REPO_NAME: The name of the repository (e.g., 'Spoon-Knife')FILE_PATH: The path to the file within the repository (e.g., 'README.md')
--branch, -b: The branch, tag, or commit SHA to download from (default: main)--output, -o: Local path to save the downloaded file (defaults to the original filename in the current directory)--help: Show help message
- Checks for
ghCLI: Verifies that theghcommand-line tool is installed and accessible. - Checks Authentication: Runs
gh auth statusto see if you are logged into GitHub. - Prompts for Login: If not authenticated, it will ask if you want to run
gh auth login. If you agree, it initiates the standardghweb-based authentication flow. - Retrieves Token: Once authenticated, it uses
gh auth tokento get an OAuth token. - Downloads File: Uses the GitHub API with the retrieved token to download the specified file.
- Saves File: Saves the downloaded content to the specified local output path.
The project uses pytest for testing. To run tests using uv:
uv run pytestThis project uses pre-commit hooks (ruff for linting and formatting, mypy for type checking) to maintain code quality. To set them up:
-
Install pre-commit:
pip install pre-commit
-
Install the hooks:
pre-commit install
Now, the hooks will run automatically before each commit.
Contributions are welcome! If you find a bug or have a feature request, please open an issue. If you'd like to contribute code, please fork the repository and submit a pull request.
This project is licensed under the MIT License - see the LICENSE file for details.