Skip to content

output-formatting.md

Latest commit

 

History

History
456 lines (313 loc) · 9.53 KB

output-formatting.md

File metadata and controls

456 lines (313 loc) · 9.53 KB
Raw

Output Formatting

fetch automatically formats and syntax-highlights response bodies based on content type.

Format Control

--format OPTION

Control response body formatting:

Value Description
auto Format when stdout is a terminal (default)
on Always format output
off Never format output 
fetch --format off example.com/api    # Raw output
fetch --format on example.com/api     # Force formatting

--color OPTION

Control syntax highlighting:

Value Description
auto Color when stdout is a terminal (default)
on Always use colors
off Never use colors 
fetch --color off example.com/api     # No colors
fetch --color on example.com/api | less -R  # Colors piped to less

Supported Content Types

JSON

Content-Types: application/json, */*+json, */*-json

Features:

  • Pretty-printing with proper indentation
  • Syntax highlighting for keys, strings, numbers, booleans, null
fetch example.com/api/users

Output:

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "active": true
}

XML

Content-Types: application/xml, text/xml, */*+xml

Features:

  • Proper indentation
  • Color-coded elements, attributes, and content
fetch example.com/api/data.xml

Output:

<?xml version="1.0" encoding="UTF-8"?>
<users>
  <user id="1">
    <name>John Doe</name>
    <email>john@example.com</email>
  </user>
</users>

YAML

Content-Types: application/yaml, application/x-yaml, text/yaml, text/x-yaml, */*+yaml

Features:

  • Syntax highlighting for keys, string values, comments, anchors/aliases, tags, and document markers
  • Original formatting preserved exactly
fetch example.com/config.yaml

Output:

server:
  host: localhost
  port: 8080
  features:
    - auth
    - logging

HTML

Content-Type: text/html

Features:

  • Proper indentation of nested elements
  • Syntax highlighting
  • Embedded CSS handling
fetch example.com

Convert readable HTML to Markdown

Use --article to extract the main readable content from an HTML response and convert it to Markdown with Legible:

fetch --article example.com/post
fetch --article --format off example.com/post > post.md
fetch --article -o post.md example.com/post

The converted HTML document starts with YAML frontmatter containing available article metadata such as title, byline, site_name, published_time, lang, dir, length, and excerpt. It also includes url, set to the final response URL after redirects. Relative links are resolved against that URL.

If the response is already text/markdown or text/x-markdown, its Markdown fetch uses the body directly and adds only url as frontmatter.

Article extraction is a body transformation rather than terminal presentation: --format, --color, and --pager only control how the resulting Markdown is displayed. Output files receive raw, uncolored Markdown. Extraction requires buffering the decoded HTML and therefore has a 16 MiB response limit.

CSS

Content-Type: text/css

Features:

  • Selector highlighting
  • Property and value coloring
  • Proper indentation
fetch example.com/styles.css

Markdown

Content-Types: text/markdown, text/x-markdown

Features:

  • Syntax highlighting for headings, bold, italic, code spans, links, images
  • Fenced code block delegation to JSON, YAML, XML, HTML, CSS formatters
  • Blockquote and list marker highlighting
fetch example.com/README.md

CSV

Content-Types: text/csv, application/csv

Features:

  • Column alignment for readability
  • Vertical "record view" for data that does not fit the terminal width
fetch example.com/data.csv

Standard output (fits terminal):

name        email               age
John Doe    john@example.com    30
Jane Smith  jane@example.com    25

Vertical mode (wide data):

--- Record 1 ---
name:  John Doe
email: john@example.com
age:   30

--- Record 2 ---
name:  Jane Smith
email: jane@example.com
age:   25

MessagePack

Content-Types: application/msgpack, application/x-msgpack, application/vnd.msgpack

Features:

  • Automatic conversion to JSON format
  • Same formatting as JSON responses
fetch example.com/api/data.msgpack

Protocol Buffers

Content-Types: application/protobuf, application/x-protobuf, application/x-google-protobuf, application/vnd.google.protobuf, */*+proto

Features:

  • Wire format parsing (without schema)
  • Field number display
  • With gRPC schema: field names and proper types

Without schema (generic parsing):

1: "John Doe"
2: 30
3: "john@example.com"

With a schema (with --proto-file or --proto-desc):

{
  "name": "John Doe",
  "age": 30,
  "email": "john@example.com"
}

See gRPC documentation for schema-aware formatting.

Server-Sent Events (SSE)

Content-Type: text/event-stream

Features:

  • Streaming output as events arrive
  • SSE-shaped event: and data: output
  • fetch formats and highlights JSON data: payloads
  • Request timeouts still apply to long-running event streams
fetch example.com/events

Output:

event: message
data: { "text": "Hello!", "user": "john" }

event: message
data: { "text": "Hi there!", "user": "jane" }

When color is enabled, fetch highlights event and data labels. It applies the JSON theme to JSON values inside data:. In automatic compression mode, fetch retries compressed SSE 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.

NDJSON / JSON Lines

Content-Types: application/x-ndjson, application/ndjson, application/x-jsonl, application/jsonl, application/x-jsonlines

Features:

  • Streaming output line by line
  • Each line formatted as JSON
fetch example.com/stream.ndjson

Output:

{"id": 1, "event": "start"}
{"id": 2, "event": "data", "value": 42}
{"id": 3, "event": "end"}

Images

Content-Type: image/*

fetch renders images directly in the terminal. See Image Rendering for details.

Output to File

-o, --output PATH

Write response body to a file:

fetch -o response.json example.com/api/data

When writing to a file, fetch disables formatting. By default, it continues to decode compression. If the response uses Content-Encoding for a .gz, .br, or .zst asset, use --compress off for a byte-for-byte download.

-o - (Stdout)

Force output to stdout, bypassing binary detection:

fetch -o - example.com/file.bin > output.bin

-O, --remote-name

Save to current directory using filename from URL:

fetch -O example.com/files/document.pdf
# Creates ./document.pdf

-J, --remote-header-name

Use filename from Content-Disposition header. If no usable header filename is available, fetch warns and falls back to the URL filename:

fetch -O -J example.com/download
# Uses server-provided filename

--clobber

Overwrite existing files:

fetch -o output.json --clobber example.com/data

Pager

By default, fetch sends response bodies to a pager when stdout is a terminal. Image responses bypass the pager. As a result, the terminal can interpret its native image protocols.

Pager Mode

Use --pager auto to page terminal stdout, --pager on to force the pager, or --pager off to disable it.

fetch --pager off example.com/large-response

Pager Environment

When 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.

The fallback less -FIRX flags are:

  • -F - Quit if output fits on screen
  • -I - Case-insensitive search
  • -R - Handle ANSI colors
  • -X - Do not clear the screen on exit

Binary Detection

When stdout is a terminal, fetch checks if the response appears to be binary data. If so, it displays a warning instead of corrupting your terminal:

warning: the response body appears to be binary (content type: application/octet-stream)

To force output:

fetch -o file.dat example.com/binary.dat
fetch -o - example.com/binary.dat

Configuration

Set defaults in your configuration file:

# Always format output
format = on

# Disable colors
color = off

# Disable pager
pager = off

Examples

Pipe to jq

fetch --format off example.com/api | jq '.users[0]'

Save Pretty JSON

fetch --format on example.com/api | tee response.json

Force Colors in Pipe

fetch --format on --color on example.com/api | less -R

Byte-for-Byte Download

fetch --compress off -o archive.tar.gz example.com/archive.tar.gz

See Also