Complete reference for all fetch command-line options.
fetch [OPTIONS] [URL]
When no scheme is provided, fetch defaults to HTTPS for hostnames. localhost
and all IP literals default to HTTP. If a schemeless hostname defaults to HTTPS
and the connection fails during setup, fetch suggests the equivalent
http:// URL for plaintext services.
fetch example.com # https://example.com
fetch localhost:3000 # http://localhost:3000
fetch 192.168.1.1:8080 # http://192.168.1.1:8080
fetch 1.1.1.1 # http://1.1.1.1
fetch http://example.com # Force HTTPSpecify the HTTP method. Default: GET, or POST when a request-body flag is
used and --method is omitted.
Alias: -X
fetch -m POST example.com
fetch -X DELETE example.com/resource/123Set custom headers. Can be used multiple times.
fetch -H "Authorization: Bearer token" example.com
fetch -H "X-Custom: value" -H "Accept: application/json" example.comAppend query parameters to the URL. Can be used multiple times.
fetch -q page=1 -q limit=50 example.comPayload source options are mutually exclusive - only one of --data, --json,
--xml, --form, or --multipart can be used per request. These options, and
--edit, default the request method to POST when --method is omitted; use
-m/--method to send the body with another method.
Send a raw request body. Content-Type is auto-detected when using file references.
fetch -d 'Hello, world!' -m PUT example.com
fetch -d @data.txt -m PUT example.com
fetch -d @- example.com < data.txtSend a JSON request body. Sets Content-Type: application/json.
fetch -j '{"hello": "world"}' example.com
fetch -j @data.json example.comSend an XML request body. Sets Content-Type: application/xml.
fetch -x '<Tag>value</Tag>' example.com
fetch -x @data.xml -m PUT example.comSend a URL-encoded form body. Can be used multiple times.
fetch -f username=john -f password=secret example.com/loginSend a multipart form body. Use @ prefix for file uploads. Can be used multiple times.
fetch -F hello=world -F file=@document.pdf example.com/uploadOpen an editor to modify the request body before sending. Uses VISUAL or EDITOR environment variables.
fetch --edit example.comAuthentication options are mutually exclusive.
HTTP Basic Authentication.
fetch --basic username:password example.comHTTP Digest Authentication. Uses a challenge-response handshake to avoid sending credentials in plain text.
Supports challenges without qop and challenges with qop=auth; unsupported digest parameters are reported as diagnostics.
fetch --digest username:password example.comHTTP Bearer Token Authentication.
fetch --bearer mysecrettoken example.comSign requests with AWS Signature V4. Requires AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables. Temporary credentials can also set AWS_SESSION_TOKEN.
fetch --aws-sigv4 us-east-1/s3 s3.amazonaws.com/bucket/keyClient certificate file for mTLS. PEM format.
fetch --cert client.crt --key client.key example.comClient private key file for mTLS. Required if --cert is a certificate-only file.
TLS requests reject --key without a client certificate.
fetch --cert client.crt --key client.key example.comWrite response body to a file. Use - for stdout (bypasses binary detection).
fetch -o response.json example.com/api/data
fetch -o - example.com/file.bin > output.binOutput files receive the decoded response body by default. If the response uses
Content-Encoding for a .gz, .br, or .zst asset, use --compress off for
byte-for-byte downloads.
Write response body to current directory using the filename from the URL.
Alias: --output-current-dir
fetch -O example.com/path/to/file.txt # Creates ./file.txtUse filename from Content-Disposition header. Requires -O. If the response
does not include a usable header filename, fetch warns and falls back to the URL
filename.
fetch -O -J example.com/downloadOverwrite existing output file (default behavior is to fail if file exists).
fetch -o output.json --clobber example.com/dataCopy the response body to the system clipboard. The response is still printed to stdout normally. Works with all response types including streaming responses (SSE, NDJSON, gRPC). Responses exceeding 1 MiB are not copied to the clipboard.
Requires a clipboard command to be available on the system:
- macOS:
pbcopy(built-in) - Linux/Wayland:
wl-copy - Linux/X11:
xcliporxsel - Windows:
clip.exe(built-in)
fetch --copy example.com/api/data
fetch --copy -o response.json example.com/api/dataDo not print the response body. Useful for checking status codes, viewing headers (with -v), or measuring timing (with --timing) without writing the body to stdout.
--discard still reads the response body to completion. Use -m HEAD when you want to ask the server to avoid transferring a response body.
Cannot be combined with --output, --remote-name, or --copy.
fetch --discard example.com
fetch --discard -v example.com # View headers only
fetch --discard --timing example.com # Measure timing only
fetch -m HEAD example.com # Avoid body transfer when supportedConvert an HTML response to Markdown by extracting its main readable content
with Legible and converting the extracted HTML with htmd.
If the response is already text/markdown or text/x-markdown, its body is
used directly. HTML output begins with YAML frontmatter containing the title,
byline, site name, published time, language, direction, text length, excerpt,
and final response URL when those details are available. Existing Markdown
receives frontmatter containing only the final response URL.
fetch --article example.com/post
fetch --article --format off example.com/post > post.md
fetch --article -o post.md example.com/postThe HTML-to-Markdown conversion uses the final URL after redirects to resolve
relative HTML links. It requires buffering the decoded response and is limited
to 16 MiB. The flag cannot be combined with gRPC, WebSocket, --discard,
--remote-name, or
--remote-header-name. An explicit Accept request header overrides article
mode's HTML-oriented default.
--format, --color, and --pager control terminal presentation of the
generated Markdown; they do not disable article extraction. Output files and
non-formatted pipes receive raw, uncolored Markdown.
Control response formatting. Values: auto, on, off.
fetch --format off example.com # Disable formatting
fetch --format on example.com # Force formattingControl colored output. Values: auto, on, off.
Alias: --colour
fetch --color off example.comControl image rendering. Values: auto, external, off.
auto- Try optimal terminal protocol with built-in decodersexternal- Allow external adapters for additional formatsoff- Disable image rendering
fetch --image external example.com/photo.avif
fetch --image off example.com/photo.jpgControl piping response body output to a pager. Values:
auto- Use the pager when stdout is a terminal (default)on- Force pager useoff- Disable the pager
fetch --pager off example.comWhen paging is enabled, fetch uses $PAGER if it is set. Set NO_PAGER to
disable the default auto pager. If $PAGER is unset, fetch falls back to
less -FIRX; when $LESS is set, fetch runs less without adding its default
flags so your LESS options apply. $PAGER is split with POSIX shell-style
quoting, but fetch launches the pager directly and does not interpret shell
operators such as pipes or redirects.
Use a named session for persistent cookie storage across invocations. Cookies set by servers are saved to disk and automatically sent on subsequent requests using the same session name.
Session names must contain only alphanumeric characters, hyphens, and underscores ([a-zA-Z0-9_-]).
# First request — server sets cookies, they get saved
fetch --session api example.com/login -j '{"user":"me"}'
# Second request — saved cookies are sent automatically
fetch --session api example.com/dashboardSession files are stored in the user's cache directory:
- Linux:
~/.cache/fetch/sessions/<NAME>.json - macOS:
~/Library/Caches/fetch/sessions/<NAME>.json
Can also be configured per-host in the configuration file.
Timeout for the connection phase (DNS resolution, TCP connect, TLS handshake) in seconds. Accepts decimal values. Independent of --timeout, which covers the entire request.
fetch --connect-timeout 5 example.com
fetch --connect-timeout 5 --timeout 30 example.comRequest timeout in seconds. Accepts decimal values. The timeout covers the full request, including response body streaming; it is also enforced for SSE, NDJSON, and gRPC streams.
fetch --timeout 30 example.com
fetch --timeout 2.5 example.comMaximum automatic redirects. Default: 10. Use 0 to disable.
fetch --redirects 0 example.com # Don't follow redirects
fetch --redirects 10 example.comMaximum number of retries for transient failures. Default: 0 (no retries).
Retries occur on connection errors and retryable status codes (429, 502, 503, 504). Non-retryable errors (4xx, TLS certificate errors) are not retried. Uses exponential backoff with jitter between attempts.
Only the final attempt's response body is written to stdout. Retry notifications are printed to stderr (suppressed with --silent).
fetch --retry 3 example.com
fetch --retry 2 --retry-delay 0.5 example.comInitial delay between retries in seconds. Default: 1. Accepts decimal values.
The actual delay uses exponential backoff (delay doubles each attempt) with ±25% jitter. The effective delay is capped at 30 seconds. If the server sends a Retry-After header, that value is used when it exceeds the computed delay, but it is also capped at 30 seconds. A warning is emitted when Retry-After is clamped unless --silent is enabled. An overall --timeout remains the final upper bound.
fetch --retry 3 --retry-delay 2 example.com
fetch --retry 3 --retry-delay 0.5 example.comUse a custom DNS server. Supports UDP DNS, DNS over TCP, DNS over TLS (DoT),
DNS over QUIC (DoQ), and DNS-over-HTTPS (DoH) for requests and DNS/TLS
inspection. Bare IP[:PORT] values use UDP DNS, which advertises EDNS(0) and
retries truncated responses over TCP. DoH URLs are queried with RFC 8484
wire-format requests, with Google-style JSON DoH retained as a compatibility
fallback.
fetch --dns-server 8.8.8.8 example.com
fetch --dns-server 1.1.1.1:53 example.com
fetch --dns-server udp://1.1.1.1:53 example.com
fetch --dns-server tcp://1.1.1.1 example.com
fetch --dns-server tls://dns.google example.com
fetch --dns-server dot://dns.google:853 example.com
fetch --dns-server quic://dns.adguard-dns.com example.com
fetch --dns-server doq://dns.adguard-dns.com example.com
fetch --dns-server https://1.1.1.1/dns-query example.comInspect DNS resolution for the URL hostname only (no HTTP request is made). Displays the resolver backend, A, AAAA, CNAME, TXT, MX, NS, SOA, SRV, CAA, SVCB, and HTTPS records when present, along with per-record TTLs, address count, record count, and lookup duration. Supports all --dns-server transports. UDP DNS inspection advertises EDNS(0) and retries truncated UDP responses over TCP; if TCP fallback cannot complete the lookup, fetch warns that the results are incomplete and exits with a non-zero status. Request-only CLI flags warn that no HTTP request will be sent and those flags have no effect; config-file defaults do not trigger this warning.
fetch --inspect-dns example.com
fetch --inspect-dns --dns-server https://1.1.1.1/dns-query example.com
fetch --inspect-dns --dns-server tls://dns.google example.comRoute request through a proxy.
fetch --proxy http://localhost:8080 example.com
fetch --proxy https://secure-proxy.example.com:8443 example.com
fetch --proxy socks5://localhost:1080 example.comHTTPS proxy TLS uses platform verification by default. Origin TLS flags such as
--ca-cert, --cert, --key, and --insecure do not apply to the proxy
handshake.
Make request over a Unix domain socket. Unix-like systems only.
fetch --unix /var/run/docker.sock http://unix/containers/jsonMinimum TLS version. This is an alias for --min-tls. Values: 1.2, 1.3.
fetch --tls 1.3 example.comMinimum TLS version. Values: 1.2, 1.3.
fetch --min-tls 1.2 example.comMaximum TLS version. Values: 1.2, 1.3. Combine with --min-tls to allow a bounded range or require an exact TLS version.
fetch --min-tls 1.2 --max-tls 1.2 example.comEncrypted Client Hello mode. Values: auto, on, off. Default: off.
auto— Use ECH if the server advertises it via DNS HTTPS/SVCB records. Falls back to GREASE ECH when no real config is found. If the server rejects the offer, the connection proceeds gracefully.on— Require ECH. Errors if the server doesn't advertise ECH in DNS, and fails if the server rejects the offer.off— Never use ECH.
ECH requires TLS 1.3 and is incompatible with --min-tls 1.2.
fetch --ech auto example.com
fetch --ech on cloudflare.comSee Encrypted Client Hello for details.
Inspect the TLS certificate chain by performing a TLS handshake only (no HTTP request is made). Displays the TLS version, cipher suite, ALPN protocol, full certificate chain with expiry status, Subject Alternative Names (SANs), and OCSP staple status. Requires an HTTPS URL. With --http 3, inspection uses a QUIC handshake and offers h3 ALPN. Request-only CLI flags (e.g. --data, --timing, --grpc) warn that no HTTP request will be sent and those flags have no effect; config-file defaults do not trigger this warning.
fetch --inspect-tls example.com
fetch --inspect-tls --http 3 example.com
fetch --inspect-tls --dns-server 1.1.1.1 example.com
fetch --inspect-tls --insecure expired.badssl.comAccept invalid TLS certificates. Use with caution.
fetch --insecure https://self-signed.example.comCustom CA certificate file.
fetch --ca-cert ca-cert.pem example.comForce a specific HTTP protocol version. Values: 1, 2, 3.
Aliases: --http1, --http2, --http3.
1- HTTP/1.12- HTTP/23- HTTP/3 (QUIC)
When --http is unset, direct HTTPS requests use DNS HTTPS/SVCB records to
discover h3 endpoints. With --dns-server, HTTPS-record discovery uses that
custom UDP or DoH resolver. Without --dns-server, it uses the platform
resolver, matching normal address lookup. This discovery is opportunistic and
does not delay the normal address lookup or TCP/TLS setup: fetch starts
TCP/TLS as soon as normal DNS produces a usable address, while a usable h3
record discovered before TCP/TLS wins races QUIC setup against it. The request
is sent once on the winning transport. If HTTPS-record discovery is too slow,
fails, is unsupported by the OS resolver, or returns no usable h3 record,
HTTPS offers h2 then http/1.1 through ALPN. Proxy and Unix socket requests
also use the normal ALPN path.
--http 1, --http 2, and --http 3 force that protocol instead of setting
a maximum version. --http 2 with a plain http:// URL is only supported for
gRPC requests, where fetch uses h2c (HTTP/2 over cleartext) for local
plaintext servers. Use --http 1 or --http 2 to opt out of automatic
HTTP/3; forced --http 3 remains strict and does not fall back to TCP.
fetch --http 1 example.com
fetch --http2 example.com
fetch --http 3 example.com
fetch --grpc --http 2 http://localhost:50051/pkg.Svc/Method # uses h2cControl response compression negotiation. Values: auto, br/brotli, gzip, zstd, off.
auto- request gzip, brotli, or zstd compression (default)br/brotli- request brotli compression onlygzip- request gzip compression onlyzstd- request zstd compression onlyoff- disable automatic compression negotiation and decompression
Output files also receive decoded/decompressed bodies by default. Use
--compress off for byte-for-byte downloads of .gz, .br, or .zst assets.
In auto mode, compressed SSE (text/event-stream) responses are retried
without Accept-Encoding so streaming events can be delivered promptly instead
of being buffered by compression.
fetch --compress br example.com
fetch --compress gzip example.com
fetch --compress off example.comRequest specific byte ranges. Can be used multiple times.
fetch -r 0-1023 example.com/file.bin
fetch -r 0-499 -r 1000-1499 example.com/file.binIncrease output verbosity. Can be stacked.
-v- Show response headers-vv- Show request and response headers with>/<prefixes-vvv- Show DNS and TLS details with>/</*prefixes--sort-headers- Sort displayed request/response headers alphabetically by name
fetch -v example.com
fetch -vv --sort-headers example.com
fetch -vvv example.comDisplay a timing waterfall chart after the response. Shows DNS, TCP, TLS, TTFB, and body download phases as a proportional bar chart. HTTP/3 reports connection setup as QUIC. Works independently of verbosity. Phases that don't apply (e.g., TLS for plaintext HTTP or connection phases for reused connections) are omitted.
fetch --timing https://example.com
fetch -T https://example.com
fetch --timing -vvv https://example.com # Both debug text and waterfallSuppress verbose output. Only errors shown on stderr.
fetch -s example.comHTTP 4xx/5xx responses exit nonzero by default; use --ignore-status to keep
the exit code at 0 when the request completes.
fetch --ignore-status example.com/not-foundInterrupted requests, such as Ctrl-C/SIGINT, exit 130.
Use ws:// or wss:// URL schemes to open a WebSocket connection:
fetch ws://echo.websocket.events
fetch wss://echo.websocket.events -d "hello"Use --ws-interactive auto|on|off to control the terminal prompt.
Use --ws-message-mode auto|text|binary to control whether outgoing messages
are sent as text or binary WebSocket frames.
Piped text/auto input is line-delimited and capped at 16 MiB per line; use
--ws-message-mode binary for larger raw streams.
Incoming WebSocket server frames and assembled messages are capped at 16 MiB.
See WebSocket documentation for details.
Enable gRPC mode. Automatically sets HTTP/2, POST method, and gRPC headers, including grpc-accept-encoding: gzip. When no local proto schema is provided, fetch automatically tries gRPC reflection before falling back to generic protobuf handling. Gzip-compressed gRPC response messages are decompressed before protobuf formatting.
fetch --grpc https://localhost:50051/package.Service/MethodList available gRPC services. Uses reflection when a URL is provided, or runs offline when --proto-file / --proto-desc is provided.
fetch --grpc-list https://localhost:50051
fetch --grpc-list --proto-desc service.pbDescribe a gRPC service, method, or message. Accepts package.Service, package.Service/Method, package.Service.Method, and full message names.
fetch --grpc-describe grpc.health.v1.Health https://localhost:50051
fetch --grpc-describe grpc.health.v1.Health/Check --proto-desc service.pbCompile .proto file(s) for gRPC requests or offline discovery. Requires protoc. Can specify multiple comma-separated paths.
fetch --grpc --proto-file service.proto -j '{"field": "value"}' localhost:50051/pkg.Svc/MethodUse a pre-compiled descriptor set file instead of --proto-file.
# Generate descriptor:
protoc --descriptor_set_out=service.pb --include_imports service.proto
# Use descriptor:
fetch --grpc --proto-desc service.pb -j '{"field": "value"}' localhost:50051/pkg.Svc/MethodAdd import paths for proto compilation. Use with --proto-file.
fetch --grpc --proto-file service.proto --proto-import ./proto localhost:50051/pkg.Svc/MethodPlaintext servers are supported via h2c (HTTP/2 over cleartext) when using an http:// URL with HTTP/2. This works for --grpc and reflection-based discovery (--grpc-list, --grpc-describe).
Specify configuration file path.
fetch --config ~/.config/fetch/custom.conf example.comExecute a curl command using fetch. Parses a curl command string and translates its flags into the equivalent fetch options. The curl prefix is optional.
Cannot be combined with other request-specifying flags (URL, --method, --header, --data, auth flags, etc.). Meta flags like --dry-run, --color, --format, --pager, and --timing can still be used.
# Basic GET
fetch --from-curl 'curl https://example.com'
# POST with JSON
fetch --from-curl "curl -X POST -H 'Content-Type: application/json' -d '{\"key\":\"value\"}' https://example.com"
# With authentication
fetch --from-curl 'curl -u user:pass https://example.com'
# Follow redirects with retry
fetch --from-curl 'curl -L --max-redirs 5 --retry 3 https://example.com'
# Preview without sending
fetch --dry-run --from-curl 'curl -X PUT -d @data.json https://example.com'
# Without the curl prefix
fetch --from-curl 'https://example.com'Supported curl flags:
| Category | Curl Flags |
|---|---|
| Request | -X, -H, -d, --data-raw, --data-binary, --data-urlencode, --json, -F, -T, -I, -G |
| Auth | -u, --digest, --aws-sigv4, --oauth2-bearer |
| TLS | -k, --cacert, -E/--cert, --key, --tlsv1.2, --tlsv1.3, --tls-max |
| Output | -o, -O, -J |
| Network | -L, --max-redirs, -m/--max-time, --connect-timeout, -x, --unix-socket, --doh-url, --retry, --retry-delay, -r |
| HTTP version | -0, --http1.1, --http2, --http3 |
| Headers | -A, -e, -b |
| Verbosity | -v, -s |
| Protocol | --proto (restricts allowed protocols; errors if URL scheme is not allowed) |
| Default-compatible no-ops | --compressed, -S/--show-error, --fail-with-body, --no-keepalive |
| Presentation compatibility | -#/--progress-bar, --no-progress-meter |
Notes:
-b/--cookieonly supports inline cookie strings (e.g.,-b 'name=value'). Cookie jar files are not supported and will return an error.- A single
-d @filenameor-d @-body streams through fetch's native request body path. Composite data bodies and--data-urlencode @filenameare materialized for curl compatibility and are capped at 16 MiB. --data-urlencodesupports@filenameandname@filenameforms for reading and URL-encoding file contents.-n/--netrcis not supported. Use--basic,--bearer, or an explicitAuthorizationheader instead.- Semantic curl flags that
fetchcannot faithfully translate, such as-f/--fail,-N/--no-buffer,--proto-default, and--proto-redir, return an error instead of being ignored.
Unknown curl flags return an error.
Print help information. Use -v --help or --verbose --help for the detailed,
colorized CLI reference. Detailed help follows --pager; use --pager off to
print directly and --color off to disable color.
Print version.
Print build information. Use -v --buildinfo to include dependency details.
Update fetch binary in place. Use with --dry-run to check for updates without installing.
See Updates for release source, verification, permissions,
background auto-update behavior, and cache/lock files.
View, install, or uninstall the Agent Skill embedded in the binary:
fetch --skill
fetch --install-skill [agents|codex|claude|gemini|pi|all]
fetch --uninstall-skill [agents|codex|claude|gemini|pi|all]agents is the default target. User scope is the default; use
--scope user|project to select the destination scope. --dry-run previews
changes, and --force permits replacing or removing a locally modified
installation.
See Agent Skill for destination paths, modification detection, and safety behavior.
Output shell completion scripts. Values: bash, fish, zsh.
echo 'eval "$(fetch --complete bash)"' >> ~/.bashrc
fetch --complete zsh > ~/.zshrc.d/_fetch
fetch --complete fish > ~/.config/fish/completions/fetch.fishPrint request information without sending, including the normalized absolute
URL. When used with --update, checks for the latest version without
installing.
fetch --dry-run -j '{"test": true}' example.com
fetch --update --dry-run| Variable | Description |
|---|---|
AWS_ACCESS_KEY_ID |
AWS access key for --aws-sigv4 |
AWS_SECRET_ACCESS_KEY |
AWS secret key for --aws-sigv4 |
AWS_SESSION_TOKEN |
AWS session token for temporary --aws-sigv4 credentials |
PAGER |
Pager command for response bodies when paging is enabled |
LESS |
Options for less; disables fetch's default less flags |
NO_PAGER |
Disable the default auto pager when set |
VISUAL / EDITOR |
Editor for --edit option |
HTTP_PROXY |
HTTP proxy URL |
HTTPS_PROXY |
HTTPS proxy URL |
ALL_PROXY |
Fallback proxy URL for any request scheme |
NO_PROXY |
Hosts, domains, IPs, or CIDR ranges to bypass proxy |
Proxy variables also support lowercase forms: http_proxy, https_proxy,
all_proxy, and no_proxy. Uppercase names are checked before lowercase names
for each variable, except uppercase HTTP_PROXY is ignored when
REQUEST_METHOD is set.
Proxy precedence is: an explicit --proxy or configured proxy = ... value,
then scheme-specific environment variables (HTTP_PROXY for HTTP requests and
HTTPS_PROXY for HTTPS requests), then ALL_PROXY, then the system proxy
configuration. NO_PROXY/no_proxy applies to environment proxies and may use
hosts, domains, IP addresses, CIDR ranges, ports, or *.
Many options support file references with the @ prefix:
@filename- Read content from file@-- Read content from stdin@~/path- Home directory expansion
fetch -j @data.json example.com
echo '{"test": true}' | fetch -j @- example.com