228 lines
12 KiB
Markdown
228 lines
12 KiB
Markdown
# 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 |
|
||
| `--show-metadata` | `<PATH>` | Display `.goget.meta` sidecar contents for debugging interrupted or resumed downloads. `<PATH>` is either the downloaded output file (sidecar is located next to it) or the sidecar file itself. Renders a human-readable summary; combine with `--json` for raw JSON. Credentials embedded in the stored URL are masked |
|
||
|
||
## 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 (TLS protocols: HTTPS, FTPS, Gemini, WebDAVS) — abort if leaf cert SHA-256 doesn't match |
|
||
| `--pinned-host-key` | `<FINGERPRINT>` | SSH host-key pinning (SFTP) — accepts `SHA256:<base64>` (`ssh-keygen -lf`) or raw hex SHA-256 |
|
||
|
||
## 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 missing one. Applies across HTTP, Gopher, and WebDAV |
|
||
| `--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. Applies across HTTP, Gopher, and WebDAV |
|
||
| `--timestamping` | — | Only download files newer than the local copy |
|
||
| `--backup-converted` | — | Back up original `.orig` files before link conversion. Applies to HTTP and WebDAV mirrors |
|
||
| `--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 |
|