# Configuration

`ghgrab` supports both saved configuration and one-off overrides.

## Saved settings

Use the `config` command to store values locally:

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

Show the current configuration:

```bash
ghgrab config list
```

Remove a saved value:

```bash
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.