DOCSEARCHbyAlgolia
Submit Docs

ghgrab

repository·main·Indexed 22 days ago

https://github.com/abhixdd/ghgrab

A TUI-based tool to download specific files or folders from Git hosting platforms like GitHub, GitLab, and Codeberg without cloning the entire repository. It features fuzzy searching, file previews, and a dedicated 'release' command for GitHub assets with OS/architecture-aware selection. It also includes an 'agent' mode for non-interactive JSON-based workflows in CI/CD or scripts.

Tokens
12.6K
Snippets
39
Records
80
Agent score
79%

What's inside ghgrab

  1. Overview of ghgrab

    main

    ghgrab is a terminal-based tool designed to let you browse and download specific files or folders from various Git forges without performing a full git clone. It features a Terminal User Interface (TUI) for smooth navigation, fuzzy searching, and file previews.

    Key Capabilities:

    • Selective Downloads: Grab specific files or folders (Batch mode) to avoid the overhead of cloning entire repositories.
    • TUI Navigation: Includes fuzzy search for navigating folders and a file previewer for source code and text files.
    • Repository Discovery: Search and filter GitHub repositories directly from the tool's home screen.
    • GitHub Specific Features: Supports GitHub LFS (Large File Storage) resolution and OS/architecture-aware selection for downloading GitHub release artifacts.
    • Supported Platforms:
      • Browsing/Downloading: GitHub, GitLab, Codeberg, Gitea, Forgejo, and compatible self-hosted instances.
      • Quick Search: GitHub only.
      • Release Downloads: GitHub only.
      • LFS Support: GitHub only.

  2. Overview of ghgrab capabilities

    main

    ghgrab is a terminal-first tool designed for browsing repositories and downloading specific assets across multiple hosting platforms. It provides two primary modes of interaction:

    1. Interactive TUI: An interactive terminal user interface for exploring repositories.
    2. CLI Commands: Direct command-line interface commands suitable for automation-friendly workflows.

    Supported Platforms:

    • Full Support (Browsing & Path Downloads): GitHub, GitLab, Codeberg, Gitea, and Forgejo.
    • GitHub-Only Features: TUI repository search and release downloads.

  3. Core capabilities of ghgrab

    main

    ghgrab is designed to pull individual files, folders, or release artifacts from supported Git forges without the overhead of cloning an entire repository.

    Key features include:

    • TUI Browsing: Browse repositories in a full-screen terminal UI.
    • Direct Access: Open a repository directly using a URL from GitHub, GitLab, Codeberg, Gitea, or Forgejo.
    • Search: Search for repositories directly from the home screen (GitHub only).
    • Previewing: Preview text and source files before committing to a download.
    • Bulk Downloads: Select multiple files or folders for a single download run.
    • Release Management: Download GitHub release assets with OS and architecture-aware matching.
    • Automation: Machine-readable commands are available for use in scripts and agent workflows.

  4. Supported platforms and features

    main

    The feature set of ghgrab varies depending on the Git forge being used:

    FeatureSupported Forges
    Repository browsing & file/folder downloadsGitHub, GitLab, Codeberg, Gitea, Forgejo, and compatible self-hosted instances
    TUI quick repository searchGitHub only
    Release downloads (ghgrab release / ghgrab rel)GitHub only
    GitHub LFS detection and download resolutionGitHub only

  5. Authenticate with GitHub via Environment Variables or Runtime Tokens

    main

    To avoid manual token management, you can use the following methods:

    Environment Variables:

    • GHGRAB_GITHUB_TOKEN
    • GITHUB_TOKEN

    Runtime Auto Mode: If you have the GitHub CLI (gh) installed, you can use --token auto or --token gh to use gh auth token at runtime. This does not save the token to your settings.

    ghgrab rel sharkdp/bat --token auto

  6. Use Agent mode for non-interactive tooling

    main

    The agent command is designed for automation and non-interactive environments. It outputs a stable JSON envelope containing:

    • api_version
    • ok (boolean)
    • command
    • data (on success)
    • error (on failure)

    Supported platforms include GitHub, GitLab, Codeberg, Gitea, and Forgejo.

    Fetch a repository tree

    Use agent tree <URL> to retrieve the repository structure.

    Download files

    Use agent download <URL> [PATHS...] to download specific files or subtrees.

    Constraint Rules:

    • --repo (entire repository) cannot be combined with positional paths.
    • --repo cannot be combined with --subtree.
    • --subtree <PATH> cannot be combined with positional paths.
    # Fetch a repository tree
ghgrab agent tree https://github.com/rust-lang/rust

# Download specific paths
ghgrab agent download https://github.com/rust-lang/rust src/tools README.md --out ./tmp

# Download a 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

  7. Install ghgrab via pipx

    main

    pipx is the recommended method for installing the Python wrapper globally. Note that if you use pipx or pip, the launcher will automatically fetch the platform-specific binary on its first use if it is not already present.

    pipx install ghgrab

  8. Install ghgrab

    main

    You can install ghgrab using several package managers depending on your environment:

    • NPM: npm install -g @ghgrab/ghgrab
    • Cargo: cargo install ghgrab
    • pipx (Recommended for Python): pipx install ghgrab
    • Nix: Use nix run github:abhixdd/ghgrab for the latest commit or nix run "github:abhixdd/ghgrab/<tag>" for a specific version.
    • Arch Linux (Aur): yay -S ghgrab-bin
    npm install -g @ghgrab/ghgrab
# or
cargo install ghgrab
# or
pipx install ghgrab

  9. Quick Start with ghgrab

    main

    To start browsing repositories interactively, simply run:

    ghgrab

    Alternatively, you can pass a repository URL directly to browse it:

    # GitHub
ghgrab https://github.com/rust-lang/rust

# GitLab
ghgrab https://gitlab.com/gitlab-org/gitlab

# Codeberg / Forgejo / Gitea
ghgrab https://codeberg.org/forgejo/forgejo

    To download files directly to your current directory without creating a subfolder, use the --cwd and --no-folder flags.

    ghgrab https://github.com/rust-lang/rust --cwd --no-folder

  11. Install ghgrab via various package managers

    main

    You can install ghgrab using several different distribution channels depending on your preferred environment:

    • Rust: Use cargo to build the native application directly.
    • Node.js: Use npm to install the package.
    • Python: Use pipx (recommended) or pip. The Python package acts as a lightweight launcher that downloads the platform binary when needed.
    • Nix: Available via Nix.
    • Arch Linux: Available via the AUR.