# ghgrab - "grab anything you want"
> A simple, pretty terminal tool that lets you search and download files from GitHub without leaving your CLI.
    
**ghgrab** provides a streamlined command-line interface for cherry-picking specific files or folders from any GitHub repository, powered by the Rust `tokio` and `ratatui` ecosystem. Focused on speed and ease of use, it offers a beautiful TUI that lets you grab exactly what you need; all without the wait times of a full `git clone`.
## Why use ghgrab?
- **No more clone-and-delete**: Grab exactly what you need, when you need it.
- **Easy on the eyes**: A clean terminal interface that makes browsing feel smooth.
- **Works where you are**: Installs quickly via NPM, Cargo, or PIP.
- **Find things fast**: Quickly search and navigate through any repo's folders with fuzzy search.
- **Repo discovery built in**: Type a repo keyword from home to search GitHub repos, filter them, then open instantly.
- **File Preview**: Preview source code and text files directly in the TUI.
- **Handles the big stuff**: Built-in support for GitHub LFS (Large File Storage).
- **Batch mode**: Select a bunch of files and folders to download them all at once.
- **Release downloads**: Grab GitHub release artifacts with OS/architecture-aware selection.
---
## Installation
### NPM
```bash
npm install -g @ghgrab/ghgrab
```
### Cargo
```bash
cargo install ghgrab
```
### pipx (Recommended for Python)
```bash
pipx install ghgrab
```
### Nix
To have the latest commit:
```bash
nix run github:abhixdd/ghgrab
```
To have a specific tagged version:
```bash
nix run "github:abhixdd/ghgrab/<tag>"
```
### Aur (Arch linux)
```bash
yay -S ghgrab-bin
```
---
### Quick Start
Just type `ghgrab` to start browsing:
```bash
ghgrab
```
Or, if you already have a link, just paste it in:
```bash
# Browse a repository
ghgrab https://github.com/rust-lang/rust
# Download to current directory directly
ghgrab https://github.com/rust-lang/rust --cwd --no-folder
```
You can also type a repository keyword on the home screen (for example `ratatui`) and press `Enter` to open repository search mode.
### CLI Flags
| `--cwd` | Forces download to the current working directory. |
| `--no-folder` | Downloads files directly without creating a subfolder for the repo. |
| `--token <TOKEN>` | Use a specific GitHub token for this run (doesn't save to settings). |
### Release Downloads
You can also download GitHub release assets directly with the user-facing `release` command or its short alias `rel`.
Basic examples:
```bash
# Download the best matching artifact for your OS and architecture
ghgrab rel sharkdp/bat
# Extract an archive after download
ghgrab rel sharkdp/bat --extract
# Download a specific release tag
ghgrab rel sharkdp/bat --tag v0.25.0
# Match a specific asset by regex
ghgrab rel sharkdp/bat --asset-regex "x86_64.*windows.*zip"
# Download into a custom directory
ghgrab rel sharkdp/bat --extract --out ./tmp/bat
# Install the selected file or extracted binary into a target directory
ghgrab rel sharkdp/bat --extract --bin-path ~/.local/bin
```
Basic release flags:
| `--tag <TAG>` | Download a specific release tag. |
| `--asset-regex <REGEX>` | Match a specific release asset by regex. |
| `--extract` | Extract archive assets after download. |
| `--out <DIR>` | Download into a custom output directory. |
| `--bin-path <DIR>` | Copy the selected file or extracted binary into the provided directory. |
| `--os <OS>` | Override detected operating system. |
| `--arch <ARCH>` | Override detected architecture. |
<details>
<summary>Show release download usage, flags, and examples</summary>
How selection works:
- If there is one clear best asset match for your OS and architecture, ghgrab downloads it directly.
- If multiple close matches exist, ghgrab shows an interactive picker in the terminal.
- Type the asset number and press `Enter` to continue.
- Type `q` and press `Enter` to cancel the picker.
```bash
# Pick a release tag explicitly
ghgrab rel sharkdp/bat --tag v0.25.0
# Match assets with a regex
ghgrab rel sharkdp/bat --asset-regex "x86_64.*linux.*tar.gz"
# Extract an archive after download
ghgrab rel sharkdp/bat --extract
# Install the selected file or extracted binary into a target directory
ghgrab rel sharkdp/bat --extract --bin-path ~/.local/bin
# Download to a custom directory
ghgrab rel sharkdp/bat --extract --out ./tmp/bat
# Force Windows x64 asset selection
ghgrab rel BurntSushi/ripgrep --os windows --arch amd64
# Allow prereleases when selecting the latest release
ghgrab rel starship/starship --prerelease
```
### Release Flags
| `--tag <TAG>` | Download a specific release tag instead of the latest matching release. |
| `--prerelease` | Allow prereleases when `--tag` is not provided. |
| `--asset-regex <REGEX>` | Match a specific release asset by regex. Useful for forcing one artifact and skipping the picker. |
| `--os <OS>` | Override detected operating system for asset selection. |
| `--arch <ARCH>` | Override detected architecture for asset selection. |
| `--file-type <TYPE>` | Prefer `any`, `archive`, or `binary` assets. |
| `--extract` | Extract archive assets after download. Supports `.zip`, `.tar.gz`, `.tgz`, and `.tar.xz`. |
| `--out <DIR>` | Download into a custom output directory. |
| `--bin-path <DIR>` | Copy the selected file or extracted binary into the provided directory. |
| `--cwd` | Download into the current working directory. |
| `--token <TOKEN>` | Use a one-time GitHub token for this run without saving it. |
### Release Examples
```bash
# Download a specific ripgrep release for Windows x64
ghgrab rel BurntSushi/ripgrep --tag 15.1.0 --os windows --arch amd64
# Use a regex to choose one exact asset
ghgrab rel sharkdp/bat --asset-regex "x86_64.*windows.*zip"
# Install an extracted binary into your local bin directory
ghgrab rel sharkdp/bat --extract --bin-path ~/.local/bin
# Use the long command form
ghgrab release sharkdp/bat
```
</details>
### Environment Variables
`ghgrab` also accepts GitHub tokens from environment variables:
- `GHGRAB_GITHUB_TOKEN`
- `GITHUB_TOKEN`
### Agent Mode
For scripts, agents, and other non-interactive workflows, `ghgrab` includes a machine-friendly `agent` command that prints a stable JSON envelope with `api_version`, `ok`, `command`, and either `data` or `error`.
```bash
# Fetch the repository tree as JSON
ghgrab agent tree https://github.com/rust-lang/rust
# Fetch the repository tree with an explicit token for scripts or agents
ghgrab agent tree https://github.com/rust-lang/rust --token YOUR_TOKEN
# Download specific paths from a repository
ghgrab agent download https://github.com/rust-lang/rust src/tools README.md --out ./tmp
# Download an explicit subtree
ghgrab agent download https://github.com/rust-lang/rust --subtree src/tools --out ./tmp
# Download the entire repository
ghgrab agent download https://github.com/rust-lang/rust --repo --out ./tmp
# Download into the current working directory without creating a repo folder
ghgrab agent download https://github.com/rust-lang/rust src/tools --cwd --no-folder
```
You can pass `--token <TOKEN>` to `agent tree` and `agent download` when an external tool, CI job, or coding agent should authenticate without relying on saved local config.
### Configuration
To manage your settings:
```bash
# Set your token
ghgrab config set token YOUR_TOKEN
# Set a custom download folder
ghgrab config set path "/your/custom/path"
# View your current settings (token is masked)
ghgrab config list
# Remove settings
ghgrab config unset token
ghgrab config unset path
```
### Theming
ghgrab supports custom color themes via a TOML config file.
- Linux/macOS: `~/.config/ghgrab/theme.toml`
- Windows: `%APPDATA%\ghgrab\theme.toml`
Any missing key falls back to the default Tokyo Night theme. Colors must use `#RRGGBB` hex format.
See [`examples/theme.toml`](examples/theme.toml) for a complete example.
### Keyboard Shortcuts (How to move around)
We've kept it pretty standard, but here's a quick cheat sheet:
| `Enter` (home) | Open URL or start repository search |
| `Enter` / `l` / `Right` (browser) | Enter directory |
| `Backspace` / `h` / `Left` | Go back to previous folder |
| `Delete` (home) | Delete character at cursor |
| `Tab` | Auto-fill `https://github.com/` (Home page) |
| `/` | Start Searching (File list) |
| `Esc` | **Exit Search** or **Return Home** (file list) or **Quit** (home screen) |
| `q` / `Q` | **Quit** (from file list) |
| `Ctrl+q` | **Force Quit** (anywhere) |
| `Space` | Toggle selection for the current item |
| `p` / `P` | **Preview** current file |
| `a` | Select All items |
| `u` | Unselect all items |
| `d` / `D` | Download selected items |
| `i` | Toggle Icons (Emoji / ASCII) |
| `g` / `Home` | Jump to Top |
| `G` / `End` | Jump to Bottom |
### Repository Search Mode Shortcuts
| `j` / `k` / `↑` / `↓` | Move selection |
| `Enter` | Open selected repository |
| `f` | Toggle include/exclude forks |
| `m` | Cycle minimum stars (`Any`, `10+`, `50+`, `100+`, `500+`, `1000+`) |
| `l` | Cycle language filter |
| `s` | Cycle sort (`Stars`, `Updated`, `Name`) |
| `x` | Reset all filters |
| `r` | Refresh current search |
| `Esc` | Return to home input |
---
## Join the community
If you find a bug, have an idea for a cool new feature, or just want to help out, we'd love to hear from you! Check out our [Contributing Guide](CONTRIBUTING.md) to see how you can get involved.
## License
Distributed under the MIT License. It's open, free, and yours to play with. See [LICENSE](LICENSE) for the fine print.