Recipes on Restish

Post JSON From a File

Mon, 01 Jan 0001 00:00:00 +0000

Use a file when the request body is too large or too important to type as shorthand on the command line. Restish reads stdin, decodes the structured document, and sends it as the request body.

restish post api.rest.sh/post < payload.json

Example payload.json:

{"name":"Alice","enabled":true}

The /post fixture echoes the parsed body so you can verify what was sent.

Variant with explicit content type:

restish post -c json api.rest.sh/post < payload.json

The explicit -c json form is useful when stdin comes from a source without a clear extension or when a script should make the request encoding obvious. For small bodies, shorthand is usually faster.

Upload a File With Multipart

Mon, 01 Jan 0001 00:00:00 +0000

Multipart requests are used for uploads that combine normal form fields with file parts. -c multipart chooses the request encoding, and @upload.txt tells Restish to send the file contents rather than the literal string.

printf 'hello from docs\n' > upload.txt
restish post -c multipart api.rest.sh/uploads 'description: docs, file: @upload.txt'

The response echoes multipart fields. If a client sends real file parts, /uploads also reports file metadata. Missing file paths fail before the request is sent. Use @@value when a text field should start with a literal @. For plain URL-encoded forms, use -c form instead; both encodings are explained in Input and Shorthand.

Create, Patch, and Delete an Item Safely

Mon, 01 Jan 0001 00:00:00 +0000

This recipe practices a full create-update-delete loop against the public example API. Because /items is shared and resettable, use a unique ID so your example does not collide with someone else’s state:

ITEM_ID="docs-$(date +%s)"
restish post api.rest.sh/items "id: $ITEM_ID, name: Demo, enabled: true, updated: 2026-04-27T00:00:00Z"
restish patch "api.rest.sh/items/$ITEM_ID" 'enabled: false, tags[]: docs'
restish delete "api.rest.sh/items/$ITEM_ID" --rsh-ignore-status-code

The first command creates an item from shorthand fields. The patch command sends only the fields you want to change. The delete command uses --rsh-ignore-status-code so cleanup remains calm if the item is already gone; see Command Behavior for how HTTP statuses map to exit codes.

Get One Field From Every Item

Mon, 01 Jan 0001 00:00:00 +0000

This is the most common shell pattern: call a list endpoint, select one field from each item, and print one plain value per line. It is useful for loops, copy-paste, and quick checks.

Browser preview

Edit the command and run it from your browser against the live docs API.

Ready

restish api.rest.sh/images -f body.self -o lines

Enable JavaScript to run this example in the browser.

Save a Response Unchanged

Mon, 01 Jan 0001 00:00:00 +0000

When stdout is redirected and you do not choose a filter, collection, metadata shortcut, or output format, Restish writes the response body bytes. That matters for binary files, structured fixtures such as CBOR, and anything another program will parse directly. Response middleware plugins are skipped for this raw-download path, so installed plugins cannot silently alter saved files.

restish api.rest.sh/bytes/64 > sample.bin
restish api.rest.sh/formats/cbor > response.cbor

For an image:

restish api.rest.sh/images/jpeg > dragonfly.jpg

Use -o json, -o yaml, or another output format when you want Restish to transform the decoded body or apply response middleware before rendering. Redirected byte output still uses the body that Go’s HTTP client exposes after any HTTP content-encoding decompression; it is not a packet capture of the exact wire transfer. The distinction is part of Restish’s output defaults. Restish’s default Accept header still prefers JSON and other text-friendly structured formats; set Accept yourself when you want the server to send a binary structured format such as CBOR.

Download a File With Headers Preserved

Mon, 01 Jan 0001 00:00:00 +0000

When you save a response to a file, stdout should contain only the body bytes. Verbose diagnostics are written to stderr, so you can redirect them to a separate file without corrupting the download.

restish -v api.rest.sh/images/jpeg > dragonfly.jpg 2> dragonfly.headers.txt

The body goes to stdout and verbose metadata goes to stderr, so the saved file stays clean. Unfiltered responses redirect as body bytes by default; see Output Defaults for how redirects choose between body bytes and formatted values.

Force JSON Output to a File

Mon, 01 Jan 0001 00:00:00 +0000

Redirected output saves response body bytes by default. Choose -o json when a script needs Restish to render decoded structured data as one JSON document. --rsh-collect matters when pagination is involved: it asks Restish to build one logical document before writing the file.

restish api.rest.sh/images --rsh-collect -o json > images.json

The file is pretty-printed by default. Add --rsh-print=b when compact JSON is more useful:

restish api.rest.sh/images --rsh-collect -o json --rsh-print=b > images.json

Open the file with jq, an editor, or another tool that expects one complete JSON value. For line-oriented pipelines, prefer -o ndjson instead; the Output guide explains document versus record formats.

Count Items Across All Pages

Mon, 01 Jan 0001 00:00:00 +0000

Counting is a whole-collection operation. If Restish streams paginated items as they arrive, a filter can start earlier but it does not necessarily see the entire logical result at once. --rsh-collect tells Restish to gather the paginated response before applying the filter.

Browser preview

Edit the command and run it from your browser against the live docs API.

Ready

restish api.rest.sh/images --rsh-collect -f '.body | length'