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. Repeat this option to set multiple headers.
fetch -H "Authorization: Bearer token" example.com
fetch -H "X-Custom: value" -H "Accept: application/json" example.comAppend query parameters to the URL. Repeat this option to append multiple parameters.
fetch -q page=1 -q limit=50 example.comPayload source options are mutually exclusive. Use only one of --data,
--json, --xml, --form, or --multipart in a request. These options and
--edit set the default request method to POST. Use -m or --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. Repeat this option to send multiple fields.
fetch -f username=john -f password=secret example.com/loginSend a multipart form body. Use the @ prefix for file uploads. Repeat this
option to send multiple fields.
fetch -F hello=world -F file=@document.pdf example.com/uploadOpen an editor to modify the request body before you send it. fetch uses the
VISUAL or EDITOR environment variable.
fetch --edit example.comAuthentication options are mutually exclusive.
HTTP Basic Authentication.
fetch --basic username:password example.comUse HTTP Digest Authentication. A challenge-response handshake prevents the
transmission of credentials in plain text. fetch supports challenges without
qop and challenges with qop=auth. It reports unsupported digest parameters.
fetch --digest username:password example.comHTTP Bearer Token Authentication.
fetch --bearer mysecrettoken example.comSign requests with AWS Signature V4. Set the AWS_ACCESS_KEY_ID and
AWS_SECRET_ACCESS_KEY environment variables. For temporary credentials, 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/dataWrite a HAR 1.2 sidecar containing the final HTTP exchange while preserving the
normal response output. The capture includes the effective request, finalized
headers and streamed request body, decoded response body, remote IP, and timing
information. Unary gRPC is supported. fetch stores protobuf frames as base64.
fetch --har request.har https://api.example.com/users
fetch -o response.json --har request.har https://api.example.com/usersfetch reserves the destination before the request and installs the file
atomically after the response. The operation obeys --clobber. PATH cannot
be - or match
--output. WebSocket, inspection, gRPC discovery, and --dry-run modes are not
supported. The initial HAR contains only the final exchange after redirects,
retries, or authentication challenges.
HAR files can contain credentials, cookies, request bodies, and response bodies.
Treat HAR files as sensitive data. Body capture has a limit of 16 MiB. For a
larger body, fetch records its size and replaces its text with a truncation
comment.
Copy 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.
Do not use this option 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 to keep cookies for subsequent commands. fetch saves
server cookies to disk. It sends the cookies in subsequent requests that use
the same session name.
Use only alphanumeric characters, hyphens, and underscores in session names
([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
You can also configure sessions for each 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 also applies to 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 # Do not follow redirects
fetch --redirects 10 example.comMaximum number of retries for transient failures. Default: 0 (no retries).
fetch retries connection errors and status codes 429, 502, 503, and 504. It
does not retry other 4xx errors or TLS certificate errors. Between attempts, it
uses exponential backoff with jitter.
fetch writes only the final response body to stdout. It writes retry
notifications to stderr. Use --silent to hide these notifications.
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 delay doubles after each attempt and includes ±25% jitter. The maximum delay
is 30 seconds. If the server sends a larger Retry-After value, fetch uses
that value up to 30 seconds. It gives a warning if it reduces Retry-After to
30 seconds. Use --silent to hide this warning. The overall --timeout value
continues to limit all attempts.
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. This operation does not make an HTTP request. The output identifies the resolver and shows available A, AAAA, CNAME, TXT, MX, NS, SOA, SRV, CAA, SVCB, and HTTPS records. It also shows each record TTL, the address and record counts, and the lookup duration.
All --dns-server transports are supported. UDP inspection advertises EDNS(0).
It retries a truncated UDP response with TCP. If the TCP retry fails, fetch
warns that the results are incomplete and exits with a nonzero status.
Request-only CLI flags have no effect with --inspect-dns. They cause a warning
that fetch does not send an HTTP request. Configuration-file defaults do not
cause 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 in 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.fetchreports an error if the server does not advertise ECH in DNS or 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 with a TLS handshake. This operation does not
make an HTTP request. The output shows the TLS version, cipher suite, ALPN
protocol, certificate chain and expiry status, Subject Alternative Names
(SANs), and OCSP staple status. Use an HTTPS URL. With --http 3, inspection
uses a QUIC handshake and offers h3 ALPN.
Request-only CLI flags have no effect with --inspect-tls. They cause a warning
that fetch does not send an HTTP request. Configuration-file defaults do not
cause 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, fetch retries compressed SSE (text/event-stream) responses
to GET and HEAD requests without Accept-Encoding. For other methods, it
keeps the compressed response and gives a warning. For immediate SSE streaming
with another method, use --compress off.
fetch --compress br example.com
fetch --compress gzip example.com
fetch --compress off example.comRequest specific byte ranges. Repeat this option to request multiple ranges.
fetch -r 0-1023 example.com/file.bin
fetch -r 0-499 -r 1000-1499 example.com/file.binIncrease output verbosity. Repeat v to increase the level.
-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. The proportional bars show DNS, TCP, TLS, time to first byte (TTFB), and body-download phases. HTTP/3 shows the connection phase as QUIC. The chart does not depend on the verbosity level. It omits phases that do not apply, such as TLS for plaintext HTTP.
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 or auto input uses line delimiters and has a limit of 16 MiB for each
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/MethodFor plaintext servers, use h2c (HTTP/2 over cleartext) with an http:// URL
and HTTP/2. You can use this configuration 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.
Do not use this option with other request options, such as a URL, --method,
--header, --data, or authentication options. You can use it with metadata
options such as --dry-run, --color, --format, --pager, and --timing.
# 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:
-band--cookiesupport only inline cookie strings, such as-b 'name=value'. Cookie jar files cause 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 obeys --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