Skip to content

getting-started.md

Latest commit

 

History

History
396 lines (284 loc) · 8.93 KB

getting-started.md

File metadata and controls

396 lines (284 loc) · 8.93 KB
Raw

Getting Started

Use this guide to install fetch and make your first HTTP request.

Installation

Installation Script (Recommended)

For macOS or Linux, use the installation script:

curl -fsSL https://raw.githubusercontent.com/ryanfowler/fetch/main/install.sh | bash

Homebrew

For macOS or Linux, install with Homebrew:

brew install ryanfowler/tap/fetch

Building from Source

If you have Rust and Cargo installed:

cargo install --git https://github.com/ryanfowler/fetch --locked

Pre-built Binaries

Download binaries for your operating system from the GitHub releases page.

Verify Installation

fetch --version

Making Your First Request

Make a GET request by providing a URL:

fetch httpbin.org/json

fetch automatically formats and highlights the response body:

HTTP/2.0 200 OK

{
  "slideshow": {
    "author": "Yours Truly",
    "title": "Sample Slide Show"
  }
}

If you do not specify a scheme, fetch uses HTTPS:

fetch example.com        # Uses https://example.com

Loopback addresses and IP literals default to HTTP:

fetch localhost:3000     # Uses http://localhost:3000
fetch 127.0.0.1:8080     # Uses http://127.0.0.1:8080
fetch 192.168.1.1:8080   # Uses http://192.168.1.1:8080
fetch 1.1.1.1            # Uses http://1.1.1.1

Specify the scheme to override the default:

fetch http://example.com   # Force HTTP
fetch https://localhost    # Force HTTPS for localhost

If a schemeless hostname such as example.com:8080 defaults to HTTPS but the port is serving plaintext HTTP, fetch includes a hint to retry with the equivalent http:// URL.

Understanding the Output

fetch separates its output into two streams:

  1. Status line (stderr) - The HTTP version, status code, and status text
  2. Response body (stdout) - The response content, automatically formatted

As a result, you can pipe the body to other tools or redirect it to a file. The status line does not go to the pipe or file:

# Save just the response body to a file
fetch httpbin.org/json > response.json

# Pipe to jq for further processing
fetch httpbin.org/json | jq '.slideshow.title'

Auto-formatting

fetch detects the content type and formats the response. It supports these formats:

  • JSON - Pretty-printed with syntax highlighting
  • XML / HTML - Indented and highlighted
  • CSS - Formatted and highlighted
  • CSV - Column-aligned table output
  • Markdown - Rendered with terminal formatting
  • YAML - Syntax highlighted
  • Images - Rendered directly in supported terminals
  • Protobuf / msgpack - Decoded and displayed as JSON
  • SSE / NDJSON - Streamed as events or lines arrive

See Output Formatting for details.

Inspecting Requests and Responses

fetch provides three levels of verbosity to help you debug HTTP requests, plus a dry-run mode to preview requests without sending them.

-v - Response Headers

Show the full response headers alongside the body:

fetch -v httpbin.org/json
HTTP/2.0 200 OK
access-control-allow-credentials: true
access-control-allow-origin: *
content-length: 429
content-type: application/json
date: Thu, 05 Feb 2026 00:33:27 GMT
server: gunicorn/19.9.0

{
  "slideshow": {
    "author": "Yours Truly",
    ...
  }
}

-vv - Request and Response Headers

Show the outgoing request headers followed by the response:

fetch -vv httpbin.org/json

Add --sort-headers to sort the displayed request and response headers by name without changing the request itself.

> GET /json HTTP/1.1
> accept: application/json, */*;q=0.5
> accept-encoding: gzip, br, zstd
> host: httpbin.org
> user-agent: fetch/v0.17.3
>
< HTTP/2.0 200 OK
< access-control-allow-credentials: true
< access-control-allow-origin: *
< content-length: 429
< content-type: application/json
< date: Thu, 05 Feb 2026 00:33:27 GMT
< server: gunicorn/19.9.0
<

{
  "slideshow": {
    "author": "Yours Truly",
    ...
  }
}

The > and < prefixes indicate outgoing request and incoming response lines.

-vvv - DNS, TLS, and Timing Details

Show the request lifecycle including DNS resolution, connection establishment, and time-to-first-byte:

fetch -vvv httpbin.org/json
> GET /json HTTP/1.1
> accept: application/json, */*;q=0.5
> accept-encoding: gzip, br, zstd
> host: httpbin.org
> user-agent: fetch/v0.17.3
>
* DNS: httpbin.org (2.7ms)
*   3.210.41.225
*   3.223.36.72
* TCP: 3.210.41.225:443 (81.9ms)
* TLS: 3.210.41.225:443 (94.7ms)
* TLS 1.2: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (176.6ms)
*   ALPN: h2
*   Resumed: no
* Certificate:
*   Subject: CN=httpbin.org
*   Issuer: CN=Amazon RSA 2048 M03,O=Amazon,C=US
*   Valid: 2025-07-20 to 2026-08-17
* TTFB: 87.9ms
*
< HTTP/2.0 200 OK
< ...

The prefixes identify each type of output:

  • > identifies outgoing request lines.
  • < identifies incoming response lines.
  • * identifies connection information.

Use this output to diagnose latency, verify the TLS configuration, and examine the connection.

--dry-run - Preview Without Sending

Preview the request without sending it:

fetch --dry-run -vv -j '{"hello":"world"}' httpbin.org/post
> POST /post HTTP/1.1
> accept: application/json, */*;q=0.5
> accept-encoding: gzip, br, zstd
> content-length: 17
> content-type: application/json
> host: httpbin.org
> user-agent: fetch/v0.17.3
>
{"hello":"world"}

Combine --dry-run with -vv to see the full request including headers and body before sending it.

Common Tasks

Changing the HTTP Method

fetch -m POST httpbin.org/post
fetch -X DELETE httpbin.org/delete

Sending JSON Data

The -j flag sets the request body and automatically adds Content-Type: application/json:

fetch -j '{"name": "test", "value": 42}' httpbin.org/post

Adding Headers and Query Parameters

Add custom headers with -H and query parameters with -q:

fetch -H "X-Custom: value" httpbin.org/get
fetch -q name=test -q page=1 httpbin.org/get

fetch encodes the query parameters and appends them to the URL.

Sending Form Data

fetch -f name=test -f value=42 httpbin.org/post

See Request Bodies for multipart forms and file uploads.

Authentication

fetch has built-in support for common authentication methods:

fetch --bearer TOKEN httpbin.org/bearer
fetch --basic user:pass httpbin.org/basic-auth/user/pass

See Authentication for AWS Signature V4 and other options.

Saving Responses

Save the response body to a file:

fetch -o response.json httpbin.org/json

Use -O to save using the filename from the URL:

fetch -O httpbin.org/image/png

Record the final HTTP exchange as a HAR 1.2 sidecar without changing response output:

fetch --har request.har httpbin.org/json

HAR files can contain credentials, cookies, and bodies. Treat HAR files as sensitive data.

Viewing Images

fetch renders images directly in terminals that support inline images, such as Kitty and iTerm2. For other terminals, it uses block characters.

fetch httpbin.org/image/png

See Image Rendering for details.

Sessions

Sessions keep cookies for subsequent requests. Use sessions for APIs that use cookie authentication:

# Log in - cookies are saved to the "myapi" session
fetch -S myapi -j '{"user":"me","pass":"secret"}' httpbin.org/cookies/set/token/abc123

# Subsequent requests automatically include the saved cookies
fetch -S myapi httpbin.org/cookies

Updating

Update fetch to the latest version:

fetch --update

Check for an available update without installing it:

fetch --update --dry-run

Or enable automatic updates in your configuration file:

auto-update = true

See Updates for details about release source, checksum verification, permissions, background behavior, and cache files.

Shell Completions

Generate shell completion scripts:

# Bash
echo 'eval "$(fetch --complete bash)"' >> ~/.bashrc

# Zsh
fetch --complete zsh > ~/.zshrc.d/fetch-completion.zsh

# Fish
fetch --complete fish > ~/.config/fish/completions/fetch.fish

Next Steps