goget/docs/configuration.md

# Configuration Reference

goget loads configuration from a TOML file at `~/.config/goget/config.toml`. CLI flags override config file values, which override defaults. The `GOGET_CONFIG` environment variable can be used to specify an alternative config path.

## Quick Start

```bash
# Generate default config
goget --init-config

# Read a value
goget --config-get timeout

# Set a value
goget --config-set timeout 5m

# List all values
goget --config-list

# Remove a value
goget --config-unset timeout
```

## Configuration Keys

### Network

| Key | Type | Default | Description |
|---|---|---|---|
| `timeout` | duration string | `30m` | Request timeout. Set to `0` for auto-calculation based on file size |
| `parallel` | int | `0` | Parallel connections. `0` = auto (4 for files >100 MB, 1 otherwise) |
| `proxy` | string | `""` | Proxy server URL (HTTP CONNECT) |
| `max_speed` | int64 | `0` | Bytes per second cap. `0` = unlimited |
| `max_retries` | int | `0` | Retry attempts on failure |
| `dns_servers` | []string | `[]` | Custom DNS servers (e.g. `["1.1.1.1","8.8.8.8"]`) |
| `ipv4_fallback` | bool | `true` | Whether to fall back to IPv4 if IPv6 is unavailable |

### HTTP

| Key | Type | Default | Description |
|---|---|---|---|
| `user_agent` | string | `Goget/1.0.0` | HTTP User-Agent header value |
| `auto_decompress` | bool | `true` | Auto-decompress gzip/deflate responses |
| `insecure_skip_verify` | bool | `false` | Skip TLS certificate verification (insecure) |
| `auto_resume` | bool | `true` | Resume download when `.goget.meta` metadata exists |
| `cookie_jar` | string | `""` | Path to Netscape-format cookie jar file |
| `keep_metadata` | bool | `false` | Keep `.goget.meta` files after download completes |

### Authentication

| Key | Type | Default | Description |
|---|---|---|---|
| `auth.username` | string | `""` | Default username for HTTP Auth |
| `auth.password` | string | `""` | Default password (⚠ stored in plain text — prefer `password_file`) |
| `auth.password_file` | string | `""` | Path to file containing the password |
| `auth.auth_type` | string | `"auto"` | `basic`, `digest`, or `auto` |
| `auth.oauth.client_id` | string | `""` | OAuth 2.0 Client ID |
| `auth.oauth.client_secret` | string | `""` | OAuth 2.0 Client Secret |
| `auth.oauth.token_url` | string | `""` | OAuth 2.0 Token endpoint URL |
| `auth.oauth.auth_url` | string | `""` | OAuth 2.0 Authorization endpoint URL |
| `auth.oauth.redirect_uri` | string | `""` | OAuth 2.0 Redirect URI |
| `auth.oauth.scopes` | []string | `[]` | OAuth 2.0 scopes |
| `auth.oauth.access_token` | string | `""` | OAuth 2.0 Access Token |
| `auth.oauth.refresh_token` | string | `""` | OAuth 2.0 Refresh Token |
| `auth.oauth.grant_type` | string | `""` | `client_credentials`, `authorization_code`, `password`, `refresh_token` |

### Recursive Downloads

| Key | Type | Default | Description |
|---|---|---|---|
| `recursive.enabled` | bool | `false` | Enable recursive downloading |
| `recursive.max_depth` | int | `3` | Maximum recursion depth |
| `recursive.follow_external` | bool | `false` | Follow links to external domains |
| `recursive.exclude_patterns` | []string | `[]` | URL patterns to exclude (simple substring match) |
| `recursive.include_patterns` | []string | `[]` | URL patterns to include (simple substring match) |
| `recursive.delay` | duration string | `100ms` | Delay between requests in recursive mode |
| `recursive.parallel` | int | `0` | Concurrent file downloads in recursive mode. `0` = sequential, `N` = up to N concurrent workers (applies to HTTP, WebDAV, FTP, SFTP) |

### Archive Extraction

| Key | Type | Default | Description |
|---|---|---|---|
| `extract.enabled` | bool | `false` | Auto-extract archives after download |
| `extract.output_dir` | string | `""` | Extraction target directory (empty = same as download dir) |
| `extract.strip_components` | int | `0` | Number of leading path components to strip |
| `extract.exclude_patterns` | []string | `[]` | File patterns to exclude from extraction |
| `extract.preserve_permissions` | bool | `true` | Preserve file permissions from archive |
| `extract.auto_detect` | bool | `true` | Auto-detect archive format (tar, tar.gz, tar.bz2, zip) |

### Output / Display

| Key | Type | Default | Description |
|---|---|---|---|
| `output_dir` | string | `"."` | Default output directory |
| `verbose` | bool | `true` | Verbose output with progress bar |
| `debug` | bool | `false` | Debug output with detailed connection info |
| `color` | string | `"auto"` | Color output: `always`, `never`, or `auto` (honors `NO_COLOR` env var) |
| `progress_style` | string | `"unicode"` | Progress bar style: `"unicode"` or `"dot"` |
| `show_eta` | bool | `true` | Display estimated time remaining |
| `checksum_algo` | string | `"sha256"` | Default checksum algorithm |

## Password Security

Passwords are stored in plain text in the config file by default. For better security, use `auth.password_file` to reference an external file, and set `GOGET_PASSWORD` as an environment variable — the config loader will prefer it.

When `config.Save()` is called, the `password`, `client_secret`, `access_token`, and `refresh_token` fields are stripped from the output to prevent accidental credential leakage.

## Config Resolution Order

1. **CLI flags** (highest priority) — override everything below
2. **Config file** — `~/.config/goget/config.toml` (or `GOGET_CONFIG` path)
3. **Defaults** (lowest priority) — hardcoded in `DefaultConfig()`

The `config.Merge()` method applies CLI overrides after loading:

```go
cfg, _ := config.Load("")
cfg.Merge(&config.CLIFlags{
    Timeout:  5 * time.Minute,
    Parallel: 8,
})
```