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

# 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:

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