From 57473d0f78dc84d2184fef187bc9218cdd8e623d Mon Sep 17 00:00:00 2001 From: Ryan Fowler Date: Wed, 4 Feb 2026 16:41:44 -0800 Subject: [PATCH] Expand getting-started guide with real examples and new sections Add example output blocks for all verbosity levels (-v, -vv, -vvv) and --dry-run, captured from real httpbin.org requests. Restructure common options into task-oriented subsections covering query params, auth, file output, and image rendering. Add new sections for sessions and auto-formatting. Update all examples to use httpbin.org endpoints. --- docs/getting-started.md | 243 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 222 insertions(+), 21 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index dd3466c..5f1d131 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -43,7 +43,20 @@ fetch --version Make a GET request by providing a URL: ```sh -fetch example.com +fetch httpbin.org/json +``` + +The response body is automatically formatted and syntax-highlighted: + +``` +HTTP/2.0 200 OK + +{ + "slideshow": { + "author": "Yours Truly", + "title": "Sample Slide Show" + } +} ``` When no scheme is provided, `fetch` defaults to HTTPS: @@ -69,50 +82,236 @@ fetch https://localhost # Force HTTPS for localhost ## Understanding the Output -When you make a request, `fetch` displays: +`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 + +This separation means you can pipe the body to other tools or redirect it to a file without the status line getting in the way: + +```sh +# 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` automatically detects the content type and formats the response with syntax highlighting. Supported formats include: + +- **JSON** - Pretty-printed with syntax highlighting +- **XML / HTML** - Indented and highlighted +- **CSS** - Formatted and highlighted +- **CSV** - Column-aligned table output +- **Images** - Rendered directly in supported terminals +- **Protobuf / msgpack** - Decoded and displayed as JSON +- **SSE / NDJSON** - Streamed line-by-line + +See [Output Formatting](output-formatting.md) 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: + +```sh +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 -1. **Status line** (to stderr) - Shows the HTTP version, status code, and status text -2. **Response body** (to stdout) - Automatically formatted based on content type +{ + "slideshow": { + "author": "Yours Truly", + ... + } +} +``` + +### `-vv` - Request and Response Headers + +Show the outgoing request headers followed by the response: + +```sh +fetch -vv httpbin.org/json +``` ``` -HTTP/1.1 200 OK +GET /json HTTP/1.1 +accept: application/json,application/vnd.msgpack,application/xml,image/webp,*/* +accept-encoding: gzip, 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 { - "name": "example", - "value": 42 + "slideshow": { + "author": "Yours Truly", + ... + } } ``` -The response body is automatically formatted and syntax-highlighted for supported content types like JSON, XML, HTML, and more. +### `-vvv` - DNS, TLS, and Timing Details + +Show the full connection lifecycle including DNS resolution, TCP connect, TLS handshake, and time-to-first-byte: + +```sh +fetch -vvv httpbin.org/json +``` + +``` +GET /json HTTP/1.1 +accept: application/json,application/vnd.msgpack,application/xml,image/webp,*/* +accept-encoding: gzip, 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 1.2: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (176.6ms) + ALPN: h2 + Session 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 +... +``` + +This is useful for diagnosing latency issues, verifying TLS configuration, and understanding connection behavior. + +### `--dry-run` - Preview Without Sending + +Preview the exact request that would be sent without actually making the HTTP call: + +```sh +fetch --dry-run -vv -j '{"hello":"world"}' -m POST httpbin.org/post +``` + +``` +POST /post HTTP/1.1 +accept: application/json,application/vnd.msgpack,application/xml,image/webp,*/* +accept-encoding: gzip, 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 + +```sh +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`: + +```sh +fetch -j '{"name": "test", "value": 42}' -m POST httpbin.org/post +``` + +### Adding Headers and Query Parameters + +Add custom headers with `-H` and query parameters with `-q`: + +```sh +fetch -H "X-Custom: value" httpbin.org/get +fetch -q name=test -q page=1 httpbin.org/get +``` + +Query parameters are URL-encoded and appended to the URL automatically. + +### Sending Form Data + +```sh +fetch -f name=test -f value=42 -m POST httpbin.org/post +``` + +See [Request Bodies](request-bodies.md) for multipart forms and file uploads. -## Common Options +### Authentication -### Change HTTP Method +`fetch` has built-in support for common authentication methods: ```sh -fetch -m POST example.com -fetch -X DELETE example.com/resource/123 +fetch --bearer TOKEN httpbin.org/bearer +fetch --basic user:pass httpbin.org/basic-auth/user/pass ``` -### Add Headers +See [Authentication](authentication.md) for AWS Signature V4 and other options. + +### Saving Responses + +Save the response body to a file: ```sh -fetch -H "Authorization: Bearer token" example.com -fetch -H "X-Custom: value" -H "Accept: application/json" example.com +fetch -o response.json httpbin.org/json ``` -### Send JSON Data +Use `-O` to save using the filename from the URL: ```sh -fetch -j '{"name": "test"}' -m POST example.com/api +fetch -O httpbin.org/image/png ``` -### View Request and Response Headers +### Viewing Images + +`fetch` can render images directly in terminals that support inline images (Kitty, iTerm2), with a block-character fallback for other terminals. ```sh -fetch -v example.com # Show response headers -fetch -vv example.com # Show request and response headers -fetch -vvv example.com # Show DNS and TLS details +fetch httpbin.org/image/png +``` + +See [Image Rendering](image-rendering.md) for details. + +## Sessions + +Sessions let you persist cookies across multiple requests. This is useful for interacting with APIs that use cookie-based authentication: + +```sh +# Log in - cookies are saved to the "myapi" session +fetch -S myapi -j '{"user":"me","pass":"secret"}' -m POST httpbin.org/cookies/set/token/abc123 + +# Subsequent requests automatically include the saved cookies +fetch -S myapi httpbin.org/cookies ``` ## Updating @@ -150,3 +349,5 @@ fetch --complete fish > ~/.config/fish/completions/fetch.fish - **[Configuration](configuration.md)** - Set up a configuration file for persistent settings - **[Authentication](authentication.md)** - Learn about authentication options - **[Request Bodies](request-bodies.md)** - Send JSON, XML, forms, and files +- **[Output Formatting](output-formatting.md)** - Formatting and syntax highlighting details +- **[Image Rendering](image-rendering.md)** - Rendering images in the terminal