# CLI Reference

Complete reference for all goget command-line flags, organized by category.

```bash
goget --url <URL> [OPTIONS]
```

## Target

| Flag | Argument | Description |
|---|---|---|
| `--url` | `<URL>` | URL to download (repeatable for multiple URLs) |

## Output

| Flag | Argument | Description |
|---|---|---|
| `--output` | `<FILE>` | Output filename or directory (default: auto-derived from URL) |
| `--restart` | — | Delete existing file and restart download from scratch |
| `--overwrite` | — | Overwrite existing file without atomic rename |
| `--content-disposition` | — | Use filename from server's `Content-Disposition` header |
| `--create-dirs` | — | Create missing parent directories of `--output` (default: true). Use `--create-dirs=false` to disable (curl `--create-dirs` / wget behavior). Ignored for stdout output |
| `--keep-timestamps` | — | Set file modification time to server's `Last-Modified` value |

## Progress

| Flag | Argument | Description |
|---|---|---|
| `--verbose` | — | Verbose output with Unicode progress bar (default enabled) |
| `--no-progress` | — | Hide progress bar, keep other output |
| `--progress` | `dot` | Dot progress bar style |
| `--quiet` | — | Suppress all output except errors |
| `--json` | — | Output progress as JSON lines for scripting (format: `{"type":"progress","current":X,"total":X,"speed":X}`) |
| `--debug` | — | Enable debug output with detailed connection info |

## Network

| Flag | Argument | Description |
|---|---|---|
| `--timeout` | `<DURATION>` | Connection timeout (`0` = smart auto-calculation based on file size) |
| `--connect-timeout` | `<DURATION>` | TCP connection establishment timeout |
| `--max-time` | `<DURATION>` | Maximum total transfer time (abort if exceeded) |
| `--max-retries` | `<N>` | Maximum retry attempts on failure |
| `--max-filesize` | `<SIZE>` | Abort if file exceeds size limit (e.g. `100MB`, `1GB`) |
| `--proxy` | `<URL>` | Proxy server URL — `http://` for HTTP CONNECT, `socks5://` (local DNS) or `socks5h://` (remote DNS) for SOCKS5, with optional `user:pass@` authentication |
| `--no-ipv4` | — | Disable IPv4 fallback (IPv6 only) |
| `--no-redirect` | — | Disable following HTTP redirects (3xx) |
| `--dns-servers` | `<IPs>` | Custom DNS servers, comma-separated (e.g. `1.1.1.1,8.8.8.8`) |
| `--bind-interface` | `<IFACE>` | Bind outgoing connections to a specific network interface (Linux only) |
| `--allow-private` | — | Allow connections to private/internal IPs (disabled by default for SSRF protection) |
| `--pinned-cert` | `<SHA256>` | Certificate pinning — abort if server cert SHA-256 doesn't match |

## HTTP / Network Flags

| Flag | Argument | Description |
|---|---|---|
| `--header` | `"K: V"` | Custom HTTP header (repeatable) |
| `--insecure` | — | Skip TLS certificate verification |
| `--cert` | `<FILE>` | Client certificate in PEM format (mTLS) |
| `--key` | `<FILE>` | Client private key in PEM format (mTLS) |
| `--data` | `"key=value"` | Send POST data (implies POST) |
| `--form` | `"field=value"` | Multipart form field (repeatable; `--form "file=@./path"` for file upload) |
| `--spider` | — | Check URL existence via HEAD request — no body downloaded |
| `--write-out` | `<FORMAT>` | Print metadata after transfer (format: `%{http_code}`, `%{size_download}`, `%{time_total}`, `%{speed_download}`) |
| `--trace-time` | — | Add HTTP timing breakdown to output (DNS, TCP, TLS, TTFB, Total) |
| `--fail` | — | Exit non-zero on HTTP 4xx/5xx response |
| `--compressed` | — | Accept-Encoding header for compressed transfer |
| `--range` | `<N>-<M>` | Download a byte range (e.g. `--range 0-999`) |
| `--post-file` | `<FILE>` | POST file contents as request body |
| `--referer` | `<URL>` | Set Referer header |

## Recursive / Spider Flags

| Flag | Argument | Description |
|---|---|---|
| `--accept` | `"*.pdf"` | Accept patterns — filename glob or MIME type (comma-separated) |
| `--no-parent` | — | Do not ascend to parent directories during recursive download |
| `--adjust-extension` | — | Append `.html` extension to text/html files without one |
| `--wait` | `<DURATION>` | Delay between requests in recursive mode |
| `--random-wait` | — | Randomize wait time (0.5x–1.5x of `--wait` value) |
| `--page-requisites` | — | Download CSS, JS, and images required to render HTML pages |
| `--span-hosts` | — | Follow links to external domains in recursive mode |
| `--convert-links` | — | Rewrite links in downloaded HTML for local offline viewing |
| `--warc-file` | `<FILE>` | Write WARC (Web ARChive) output for archival |
| `--dry-run` | — | List all URLs that would be downloaded in recursive/mirror mode without saving files to disk |
| `--progress` | `dot` | Dot progress bar style |
| `--no-clobber` | — | Skip download if file already exists |

## Recursive / Mirror

| Flag | Argument | Description |
|---|---|---|
| `--recursive` | — | Enable recursive downloading — follow links from HTML pages |
| `--mirror` | — | Mirror entire website (infinite depth, convert links) — shorthand for `--recursive --convert-links --page-requisites` |
| `--max-depth` | `<N>` | Maximum recursion depth |
| `--follow-external` | — | Follow links to domains other than the starting domain |
| `--exclude-pattern` | `<P>` | Exclude URL patterns (glob, comma-separated) |
| `--no-convert-links` | — | Don't convert links in HTML during mirror (faster, but not offline-ready) |
| `--no-mirror-assets` | — | Don't download CSS, JS, and images during mirror |
| `--no-robots` | — | Don't respect `robots.txt` during mirroring |
| `--rate-limit` | `<RATE>` | Maximum download speed (e.g. `1MB/s`, `500KB/s`, `0` = unlimited) |
| `--domains` | `<LIST>` | Restrict recursion to listed domains (comma-separated) |
| `--reject` | `<PATTERN>` | Reject URL patterns (glob) |
| `--cut-dirs` | `<N>` | Ignore N directory components when creating local filenames |
| `--proto-dirs` | — | Create protocol-prefixed directories (http/, ftp/ etc.) |
| `--adjust-extension` | — | Append `.html` to text/html files missing an extension |
| `--timestamping` | — | Only download files newer than the local copy |
| `--backup-converted` | — | Back up original `.orig` files before link conversion |
| `--recursive-parallel` | `<N>` | Number of concurrent file downloads in recursive mode across all protocols (HTTP, WebDAV, FTP, SFTP). `0` = sequential (default) |
| `--continue` | — | Continue getting partially-downloaded file |

## Download Management

| Flag | Argument | Description |
|---|---|---|
| `--queue` | — | Add URL to the download queue (see `--queue-file`) |
| `--queue-list` | — | List all items in the queue |
| `--queue-process` | — | Process (download) all pending items in the queue |
| `--queue-clear` | — | Remove completed items from the queue |
| `--queue-file` | `<PATH>` | Custom queue file path (default: `~/.config/goget/queue.json`) |
| `--queue-priority` | `<N>` | Priority for queued item (1–10, higher = processed first) |
| `--batch-file` | `<FILE>` | Read URLs from a file, one URL per line |
| `--input-file` | `<FILE>` | Read URLs from a file (alias for `--batch-file`) |
| `--schedule` | `<TIME>` | Schedule download — absolute (`"2026-06-01 02:00"`) or cron (`"0 2 * * *"`) |
| `--on-complete` | `<CMD>` | Run shell command after successful download (env: `GOGET_OUTPUT`, `GOGET_SIZE`, `GOGET_URL`) |

## Authentication

| Flag | Argument | Description |
|---|---|---|
| `--username` | `<USER>` | Username for HTTP Basic/Digest authentication |
| `--password` | `<PASS>` | Password (prefer `--password-file` for security) |
| `--password-file` | `<FILE>` | Read password from file |
| `--auth-type` | `<TYPE>` | Authentication type: `basic`, `digest`, or `auto` |
| `--cookie-jar` | `<FILE>` | Load and save cookies in Netscape format |
| `--cookie` | `"n=v"` | Set cookie from CLI (repeatable) |
| `--oauth-client-id` | `<ID>` | OAuth 2.0 Client ID |
| `--oauth-client-secret` | `<S>` | OAuth 2.0 Client Secret |
| `--oauth-token-url` | `<URL>` | OAuth 2.0 Token endpoint URL |
| `--oauth-auth-url` | `<URL>` | OAuth 2.0 Authorization endpoint URL |
| `--oauth-redirect-uri` | `<URI>` | OAuth 2.0 Redirect URI |
| `--oauth-scopes` | `<S>` | OAuth 2.0 scopes (comma-separated) |
| `--oauth-grant-type` | `<TYPE>` | OAuth 2.0 grant type: `client_credentials`, `authorization_code`, `password`, `refresh_token` |
| `--oauth-access-token` | `<T>` | OAuth 2.0 access token |
| `--oauth-refresh-token` | `<T>` | OAuth 2.0 refresh token |

## Upload

| Flag | Argument | Description |
|---|---|---|
| `--upload` | — | Upload file instead of downloading |
| `--upload-method` | `<M>` | HTTP method: `PUT` or `POST` (default: `PUT`) |
| `--upload-file` | `<FILE>` | Path to file to upload |
| `--form-data` | `"k=v"` | Form data for multipart upload (comma-separated) |
| `--file-field` | `<NAME>` | Form field name for file upload (default: `file`) |

## Verification

| Flag | Argument | Description |
|---|---|---|
| `--checksum` | `<HASH>` | Expected checksum (hex string) |
| `--checksum-algo` | `<ALG>` | Algorithm: `sha256`, `sha512`, `blake2b`, `sha3-256`, `sha3-512`, `md5` (default: `sha256`) |
| `--checksum-file` | `<FILE>` | Read expected checksum from SHA256SUMS-format file |

## PGP / GPG

| Flag | Argument | Description |
|---|---|---|
| `--pgp-decrypt` | — | Decrypt PGP-encrypted file after download |
| `--pgp-verify` | — | Verify PGP detached or inline signature |
| `--pgp-sig` | `<FILE>` | Path to detached signature file (`.asc`, `.sig`) |
| `--pgp-key` | `<FILE>` | Path to PGP key file |
| `--pgp-passphrase` | `<PASS>` | Passphrase for private key |
| `--pgp-passphrase-file` | `<F>` | Read passphrase from file |

## Metalink

| Flag | Argument | Description |
|---|---|---|
| `--metalink` | — | Treat URL as a Metalink file (multi-source download) |
| `--metalink-file` | `<PATH>` | Path to local Metalink file (`.meta4`, `.metalink`) |

## SSL / TLS

| Flag | Argument | Description |
|---|---|---|
| `--ssl-key-log` | `<FILE>` | Log TLS master secrets to file (SSLKEYLOGFILE for Wireshark) |
| `--known-hosts` | `<FILE>` | Custom SSH `known_hosts` file path for SFTP |
| `--ssh-insecure` | — | Skip SSH host key verification for SFTP (accept any key) |
| `--cacert` | `<FILE>` | Custom CA certificate bundle |

## Configuration

| Flag | Argument | Description |
|---|---|---|
| `--config` | `<FILE>` | Path to configuration file |
| `--init-config` | — | Generate default config file at `~/.config/goget/config.toml` |
| `--config-get` | `<KEY>` | Get value (e.g. `timeout`, `parallel`) |
| `--config-set` | `<K>` `<V>` | Set value (e.g. `--config-set timeout 5m`) |
| `--config-list` | — | List all config keys and values |
| `--config-unset` | `<KEY>` | Remove config key |

## Information

| Flag | Argument | Description |
|---|---|---|
| `--info` | `<URL>` | Show file metadata without downloading (size, type, server info) |
| `--benchmark` | `<URL>` | Benchmark download speed (downloads first 10 MB) |
| `--generate-man-page` | — | Generate man page in troff format and exit |
| `--completion` | `<SHELL>` | Generate shell completion for `bash`, `zsh`, or `fish` |
| `--help` | — | Show help text and exit |
| `--version` | — | Show version and exit |

## Additional Flags

| Flag | Argument | Description |
|---|---|---|
| `--parallel` | `<N>` | Number of parallel chunk connections (`0` = auto, `1` = sequential) |
| `--max-speed` | `<RATE>` | Maximum download speed in bytes/sec or human format |
| `--no-private` | — | Disable `netrc` and auth file reading |
| `--glob` | `<PATTERN>` | URL glob pattern expansion (e.g. `--glob "https://example.com/file[1-3].zip"`) |
| `--retry-all-errors` | — | Retry on any HTTP 4xx/5xx response |
| `--retry-delay` | `<DURATION>` | Custom delay before retry |
| `--hsts-file` | `<FILE>` | Custom HSTS cache file path |