Configuration

ghgrab supports both saved configuration and one-off overrides.

Saved settings

Use the config command to store values locally:

ghgrab config set token YOUR_TOKEN
ghgrab config set path "/your/custom/path"

Show the current configuration:

ghgrab config list

Remove a saved value:

ghgrab config unset token
ghgrab config unset path

Authentication

You can provide a token in three ways:

  1. with --token <TOKEN|auto|gh> for a single command,

  2. with a saved config token,

  3. with an environment variable.

When --token auto or --token gh is used, ghgrab calls gh auth token at runtime and uses that token for the current run only (it is not saved).

Supported environment variables:

  • GHGRAB_GITHUB_TOKEN

  • GITHUB_TOKEN

The command-line flag takes precedence over environment variables, and environment variables take precedence over saved config. If no token is found, ghgrab may attempt GitHub CLI token discovery as a runtime fallback.

The saved config field and environment variable names are still GitHub-oriented for backward compatibility, but the --token flag itself is also used for GitLab, Gitea, Forgejo, and Codeberg requests when those servers require authentication.

Download destination

You can control where files are written by using:

  • ghgrab config set path ... for a saved default,

  • --out <DIR> for command-specific output,

  • --cwd to force downloads into the current working directory.

Use --no-folder when you want downloaded paths placed directly in the target directory instead of a repository-named folder.

When a token helps

Token support is especially useful when:

  • you hit anonymous API rate limits,

  • you are scripting against private repositories that your token can access,

  • you want more reliable automation in CI or agent workflows.

Notes:

  • gh auth token auto-discovery is GitHub CLI based, so it is mainly useful for GitHub workflows.

  • TUI repository search still uses GitHub search only.

  • Release downloads still use GitHub releases only.