Reference on Restish

Commands

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

Restish commands fall into a few groups: generic HTTP requests, API management, configuration and setup, utilities, generated API commands, and plugin commands. Run any command with --help for exact flags and operational notes.

Generic HTTP Commands

Use generic HTTP commands for one-off requests or APIs without a useful OpenAPI description.

restish api.rest.sh/
restish get api.rest.sh/get
restish post api.rest.sh/post 'name: Alice'
restish patch api.rest.sh/patch 'enabled: false'

A bare URL without a body sends GET. A bare URL with shorthand or stdin body input sends POST.

Generic HTTP Commands

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

Generic HTTP commands work without API registration. They still use Restish profiles, auth, TLS, retries, cache, filtering, pagination, and output.

Generated Command Reference

Generated from the current Cobra command tree.

`restish get`

Perform an HTTP GET request

Perform an HTTP GET request against a full URL or registered API short-name URL.

Use generic HTTP commands for one-off requests, scripting, and APIs that are not registered with api connect. Restish still applies global request flags, profile settings for registered API short names, response normalization, output formatting, filtering, retries, caching, pagination, and plugin hooks.

Global Flags

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

Global flags apply across generic requests, generated API commands, utilities, and many plugin-delegated requests. Ordinary command help shows common flags; --help-all shows the full grouped reference:

restish get --help
restish get --help-all

Generated Flag Reference

Generated from the current root persistent flags.

--help-all

Type: bool; default: false

Show all inherited Restish flags in help

--rsh-auth

Type: string; default: none

Generated operation auth override, e.g. “PartnerKey” or “UserOAuth+PartnerKey”

API Management

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

restish api manages configured APIs and generated command sources.

Generated Command Reference

Generated from the current Cobra command tree.

`restish api`

Manage registered API configurations

Manage APIs registered in the local Restish config.

Registered APIs turn OpenAPI descriptions into generated commands with shell completion, persistent profiles, and auth-aware requests. Use api connect to add an API, api sync after its OpenAPI document changes, and api set for local profile edits.

Config Command

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

Use restish config when you need to inspect or change local Restish state: registered APIs, profiles, auth settings, cache preferences, plugin config, and terminal themes.

For field-level config structure and precedence, see Config.

Common Examples

restish config path
restish config show
restish config show -o json
restish config trust
restish config set 'cache.max_size: 500MB'
restish config theme list
restish config theme set one-dark-pro
restish config theme reset

Use api set for edits that belong to one registered API. Use config set when the patch targets top-level config, shared auth profiles, cache settings, plugin settings, or themes.

Cache Command

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

Use restish cache to inspect or clear cached HTTP responses. This cache is separate from the OpenAPI spec cache and OAuth/auth token cache.

Common Examples

restish cache info
restish cache info -o json
restish cache clear
restish cache clear example
restish cache clear --direct

Use api sync when you need to refresh a cached OpenAPI document. Use api auth logout when you need to clear cached auth tokens.

Config and cache roots are separate. RSH_CONFIG_DIR changes which config file Restish reads, but it does not by itself isolate the HTTP/spec cache; set RSH_CACHE_DIR as well when tests, bug reports, or audits need a clean cache.

Example API

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

The docs use api.rest.sh whenever a live endpoint makes a Restish workflow clearer. Restish infers https:// for host-like request targets, while config values and OpenAPI metadata still use full URLs. The API is intentionally broad: it has OpenAPI discovery, request echoing, auth fixtures, forms, uploads, streaming, pagination, retries, content negotiation, binary responses, redirects, and safe CRUD examples.

Configure it once when you want short API-aware commands:

restish api connect example api.rest.sh 'prompt.api_key: docs-key'
restish example --help

Use a host-like URL when you want to stay in generic HTTP mode:

Doctor Command

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

Use restish doctor when behavior looks environment-specific: the wrong config file is being read, permissions are suspicious, shell setup is incomplete, plugins are missing, or a registered API needs a health check.

Common Examples

restish doctor
restish doctor -o json
restish doctor api example
restish doctor api example --check-network
restish doctor plugin mcp

Prefer JSON output when attaching diagnostics to an issue or comparing results across machines.

TTY human output colorizes status words when terminal color is enabled. JSON output is stable and uncolored.

OpenAPI Extensions and Generated Commands

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

Restish turns OpenAPI operations into CLI commands. This reference is for API authors and maintainers who want the generated command surface to feel natural: stable names, useful help, predictable parameters, auth setup, and documented Restish extensions.

Minimum Good Operation

paths:
 /items/{item-id}:
 get:
 operationId: getItem
 summary: Get one item
 parameters:
 - name: item-id
 in: path
 required: true
 schema:
 type: string
 responses:
 "200":
 description: Item

This can become:

Shell Command

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

Use restish shell to configure interactive shell behavior and generate or install completion scripts. Shell setup prevents URL, query, filter, and shorthand characters from being rewritten before Restish sees them.

For the workflow explanation, see Shell Setup.

Common Examples

restish shell setup zsh --dry-run
restish shell setup zsh
restish shell setup zsh --no-completion
restish shell completion zsh
restish shell completion bash
restish shell completion install fish

Quote URLs, filters, and shorthand in scripts even after shell setup. The wrapper is for day-to-day interactive use.

Utility Commands

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

Utility commands inspect supporting HTTP and runtime details without changing remote resources. Use them to check TLS certificates, extract hypermedia links, and report the Restish version.

Common Examples

restish cert api.rest.sh
restish cert api.rest.sh --warn-days 30
restish links api.rest.sh/images next
restish version

Generated Command Reference

Generated from the current Cobra command tree.

`restish cert`

Show the TLS certificate chain for a server

Show the TLS certificate chain for an HTTPS server.

Config

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

Restish config is the trust boundary for API base URLs, generated command sources, profiles, auth, TLS, plugins, cache settings, and terminal-output themes.

Location And Selection

Default config lives in a Restish config directory as restish.json:

Platform	Default path
macOS, Linux, and other Unix-like systems	`~/.config/restish/restish.json`
Windows	`%APPDATA%\restish\restish.json`

Config path precedence:

--rsh-config <file>
RSH_CONFIG=<file>
RSH_CONFIG_DIR=<dir>/restish.json
XDG_CONFIG_HOME/restish/restish.json
platform default

restish --rsh-config ./restish.json api list
RSH_CONFIG=./restish.json restish api list

An explicit config file is the whole source of truth for that invocation. If it is missing, Restish errors instead of falling back to user config.

Profiles

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

Profiles are named request defaults. Most profiles live under an API entry and let the same command run against different environments, auth contexts, headers, query params, or TLS settings.

Example

{
 "apis": {
 "example": {
 "base_url": "https://api.rest.sh",
 "profiles": {
 "default": {},
 "json": {
 "headers": ["Accept: application/json"]
 },
 "debug": {
 "query": ["trace=docs"],
 "headers": ["X-Debug: true"]
 },
 "token": {
 "auth": {
 "type": "bearer",
 "params": {
 "token": "env:DOCS_TOKEN"
 }
 }
 }
 }
 }
 }
}

Use a profile with -p or RSH_PROFILE:

restish -p json example list-images
RSH_PROFILE=json restish example list-images

The command-line flag wins over RSH_PROFILE.

Environment Variables

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

Environment variables are useful for local defaults and automation, but command line flags should be used when one invocation must be explicit.

Generated from production source environment-variable usage plus Go’s standard proxy environment contract.

Config And Profiles

Variable	Purpose	Source
`RSH_CONFIG`	Explicit config file path. It selects one config file for the invocation.	config paths
`RSH_CONFIG_DIR`	Config directory override; Restish uses `restish.json` inside this directory.	config paths
`RSH_CACHE_DIR`	HTTP/spec cache directory override.	config paths
`XDG_CONFIG_HOME`	Base config directory; Restish uses `$XDG_CONFIG_HOME/restish/restish.json`.	config paths
`XDG_CACHE_HOME`	Base cache directory; Restish uses `$XDG_CACHE_HOME/restish`.	config paths
`RSH_PROFILE`	Default API profile name. The `--rsh-profile` flag wins for one command.	global flags
`RSH_AUTH`	Default generated-operation auth override, such as `PartnerKey` or `UserOAuth+PartnerKey`.	global flags

Request Defaults

Variable	Purpose	Source
`RSH_HEADER`	Comma-separated default request headers in `Name: Value` form; escape literal commas as `\,`.	global flags
`RSH_QUERY`	Comma-separated default query parameters in `key=value` form; escape literal commas as `\,`.	global flags
`RSH_TIMEOUT`	Default request timeout such as `15s`.	global flags
`RSH_FILTER`	Default response filter expression.	global flags
`RSH_NO_CACHE`	Bypass HTTP cache where supported.	global flags
`RSH_INSECURE`	Disable TLS certificate verification when truthy.	global flags
`RSH_RETRY`	Default retry count where supported.	global flags
`RSH_RETRY_UNSAFE`	Allow retry replay for POST, PUT, PATCH, and DELETE when truthy.	global flags
`RSH_RETRY_MAX_WAIT`	Default cap for `Retry-After` / `X-Retry-In`, such as `30s`.	global flags

Editor And Terminal

Variable	Purpose	Source
`RSH_OUTPUT_FORMAT`	Default rendered body format for `-o` / `--rsh-output-format`.	global flags
`RSH_PRINT`	Default `--rsh-print` output parts, such as `b` for compact rendered output in scripts.	global flags
`VISUAL`	Preferred editor for `config edit` and `edit`.	editor
`EDITOR`	Fallback editor for `config edit` and `edit`.	editor
`GLAMOUR_STYLE`	Markdown rendering style for markdown-formatted terminal output.	output
`RSH_IMAGE_PROTOCOL`	Force terminal image rendering protocol: `kitty`, `iterm2`, or `halfblock`.	output
`KITTY_WINDOW_ID`	Used to auto-detect Kitty image support.	output
`TERM`	Used to auto-detect Kitty terminal support.	output
`TERM_PROGRAM`	Used to auto-detect iTerm2-style image support.	output
`COLUMNS`	Terminal width hint for half-block image rendering.	output
`SHELL`	Used for first-run shell setup hints.	shell setup
`NO_COLOR`	Disable color where respected.	output
`NOCOLOR`	Disable color; supported as an older spelling alongside `NO_COLOR`.	output
`COLOR`	Force color where respected.	output

Plugin Runtime

Variable	Purpose	Source
`RSH_COMMAND_PLUGIN_DISCOVERY_TIMEOUT`	Override command-plugin startup discovery timeout.	plugin runtime
`RSH_COMMAND_PLUGIN_SHUTDOWN_GRACE`	Override command-plugin shutdown grace period.	plugin runtime

Plugin Installation

Variable	Purpose	Source
`GITHUB_TOKEN`	Bearer token used for GitHub release API requests during `restish plugin install owner/repo plugin`.	plugin install

Proxies

Variable	Purpose	Source
`HTTPS_PROXY`	Standard Go HTTPS proxy setting used by Restish HTTP transports.	Go HTTP transport
`HTTP_PROXY`	Standard Go HTTP proxy setting used by Restish HTTP transports.	Go HTTP transport
`NO_PROXY`	Standard Go proxy bypass list used by Restish HTTP transports.	Go HTTP transport

Flags override environment defaults for one command. Restish also uses Go’s standard proxy environment behavior:

Auth

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

Auth configuration lives on a profile. Use auth when one credential applies to the API/profile, and use credentials when generated OpenAPI operations need different security schemes or alternatives.

Auth Types

Type	Required params	Optional params	Effect
`bearer`	`token`		Sets `Authorization: Bearer <token>`.
`http-basic`	`username`	`password`	Sets HTTP Basic auth. If `password` is omitted and prompting is available, Restish prompts.
`api-key`	`in`, `name`, `value`		Sends an API key in a `header`, `query`, or `cookie`.
`oauth-client-credentials`	`client_id`, `client_secret`, plus `token_url` or `issuer_url`	`auth_method`, `scopes`, provider-specific token params such as `audience`	Fetches and caches a bearer token with the OAuth client credentials flow.
`oauth-authorization-code`	`client_id`, plus `authorize_url` and `token_url`, or `issuer_url`	`client_secret`, `auth_method`, `scopes`, `redirect_scheme`, `redirect_port`, `redirect_path`, `redirect_cert`, `redirect_key`, `callback_success_html`, `callback_error_html`, provider-specific token params	Runs an OAuth authorization-code flow with PKCE and caches the token.
`oauth-device-code`	`client_id`, plus `device_authorization_url` and `token_url`, or `issuer_url`	`client_secret`, `auth_method`, `scopes`, provider-specific token params	Runs the OAuth device-code flow and caches the token.
`external-tool`	`commandline`	`omitbody`, `output`	Runs a local helper that can mutate request headers or URI.

OAuth auth_method accepts client_secret_post by default or client_secret_basic. OAuth endpoints must use HTTPS except for localhost or loopback development URLs. issuer_url uses OIDC discovery when direct endpoint URLs are absent. Unknown non-reserved OAuth params are forwarded to token requests, which is how provider-specific values such as audience are sent.

Content Types

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

Restish separates two decisions:

Request encoding: -c or --rsh-content-type controls how a request body is sent.
Response rendering: -o controls how a decoded response is printed.

HTTP Accept headers ask the server for a representation. Output formats do not change what the server sends.

Built-In Types

restish doctor lists the registered content type aliases. Use JSON doctor output when you need MIME types, suffixes, and quality values:

restish doctor
restish doctor -o json

Alias	MIME types
`json`	`application/json`
`ndjson`	`application/x-ndjson`, `application/ndjson`, `application/jsonl`, `application/jsonlines`
`xml`	`application/xml`, `text/xml`
`yaml`	`application/yaml`, `application/x-yaml`, `text/yaml`, `text/x-yaml`
`cbor`	`application/cbor`
`msgpack`	`application/msgpack`, `application/x-msgpack`, `application/vnd.msgpack`
`binary`	`application/octet-stream`
`ion`	`application/ion`, `text/ion`
`form`	`application/x-www-form-urlencoded`
`multipart`	`multipart/form-data`
`sse`	`text/event-stream`
`text`	`text/plain`, `text/*`

JSON-family structured types with +json, such as application/problem+json, decode as JSON. Structured suffixes win before broad wildcards, so a response labeled text/example+json is treated as JSON rather than plain text/* unless an exact handler is registered for that MIME type. XML-family media types with +xml, such as application/soap+xml, use the XML handler.

Output Formats

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

Output formats decide how the selected body/value is rendered after decoding, pagination or streaming, and filtering. They do not print HTTP status or headers; use --rsh-print for those exchange parts. They also do not change request Accept headers or server-side content negotiation. Redirected rendered document output is pretty by default; pass --rsh-print=b for compact rendered JSON.

Document Formats

Document formats produce one coherent result:

Format	Use
`auto`	Default body/value presentation.
`json`	One JSON document.
`yaml`	One YAML document.
`cbor`	One CBOR document.
`gron`	Greppable path/value assignments.
`table`	Terminal table output for records or object collections.
`image`	Terminal image rendering for image responses.

restish api.rest.sh/images -o auto
restish api.rest.sh/images --rsh-collect -o json
restish api.rest.sh/images -o yaml
restish api.rest.sh/example -o gron
restish api.rest.sh/images/png

For redirects, unfiltered responses already write body bytes:

Output Defaults

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

Restish chooses output defaults from context. Scripts should still pass -o when the expected shape matters.

Main Rule

Context	Default
Interactive terminal, unfiltered response	response status, headers, and formatted body on stdout
Redirected stdout, unfiltered response with no explicit output transform	response body bytes
Explicit filter selecting a scalar	plain scalar text
Explicit filter selecting structured data	pretty JSON-shaped auto output
Paginated items with no collect mode	stream item results as they arrive
Live streams	record-oriented output; use `ndjson` or `lines` for scripts; plain `-o json` requires `--rsh-collect` and finite `--rsh-max-items`

Examples

restish api.rest.sh/images
restish api.rest.sh/images -o json > images.json
restish api.rest.sh/images/jpeg > dragonfly.jpg
restish api.rest.sh/formats/cbor > response.cbor
restish api.rest.sh/formats/cbor -o json > response.json
restish api.rest.sh/events --rsh-max-items 3 -o ndjson

Use --rsh-print=b when a script wants compact rendered JSON instead of the pretty default for transformed output:

Shorthand

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

Shorthand is Restish’s compact structured-input language. It builds JSON-shaped values for request bodies, patches structured stdin, and powers config set, api set, and edit patch arguments.

Quick Shape

Shorthand	Result
`name: Alice`	`{"name":"Alice"}`
`user.name: Alice`	`{"user":{"name":"Alice"}}`
`tags[]: docs`	`{"tags":["docs"]}`
`items[0].name: first`	`{"items":[{"name":"first"}]}`
`base{one: 1, two.three: 3}`	`{"base":{"one":1,"two":{"three":3}}}`

Use quotes around an entire shorthand argument when it contains spaces, brackets, ?, &, |, or other shell-sensitive characters:

restish post api.rest.sh/post 'user.name: Alice, tags[]: docs'

Assignments

An assignment is path: value. Paths use dots for nested object fields and brackets for array positions.

Query Syntax

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

Restish filters the normalized response before formatting. Use shorthand for direct paths, projections, recursive search, and simple selection. Use jq for larger transforms.

Roots

Most filters start from one of these normalized roots:

Root	Meaning
`status`	Numeric HTTP status code.
`headers`	First value for each response header.
`headers_all`	Complete header map for repeated values. Use jq syntax such as `.headers_all["Set-Cookie"]` when you need it.
`links`	Normalized hypermedia links.
`body`	Decoded response body.
`proto`	HTTP protocol string such as `HTTP/2.0`.

restish api.rest.sh/ -f headers.Content-Type
restish api.rest.sh/images -f links.next
restish api.rest.sh/example -f body.basics.profiles

Paths And Indexes

Use dots for object fields and brackets for array positions:

Bulk Command

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

restish-bulk is a command plugin for workflows where a collection needs to be pulled down, edited locally, and pushed back in a controlled way. It is useful for repeatable content or data maintenance tasks where one request at a time is too slow or too error-prone.

Examples

restish bulk init api.rest.sh/books
restish bulk status
restish bulk pull
restish bulk diff
restish bulk push
restish bulk reset

init starts a bulk workspace for a collection. status shows local and remote state. pull refreshes local data. diff previews local edits. push sends local changes only when it has a safe precondition such as an ETag, Last-Modified value, or matching local/remote version metadata. reset returns the workspace to a clean state.

Edit Command

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

edit is for APIs where a resource is easier to review in an editor than to rebuild from command-line arguments. Restish fetches the resource, opens it in your editor, then sends the changed document back with the appropriate update request.

Generated Command Reference

Generated from the current Cobra command tree.

`restish edit`

Fetch a resource, edit it locally, then send it back

Fetch a resource, edit it locally, then send the changed representation back.

Plugin Command

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

Plugins extend Restish without making every feature part of the core binary. Operators use the plugin command to install, list, remove, and debug those extensions. Authors use the plugin reference pages to understand the protocols.

Installed plugins are executable code and run at your own risk. Restish checks manifests and declared capabilities; it does not sandbox plugins or verify publisher identity.

Generated Command Reference

Generated from the current Cobra command tree.

Plugin Manifest

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

A plugin manifest tells Restish what a plugin is, what protocol version it uses, and which hooks or command surfaces it provides.

Generated Schema

Generated from plugin/manifest.go and plugin/messages.go.

`Manifest`

Manifest is the metadata a plugin reports when called with –rsh-plugin-manifest. Plugin authors populate and write this with WriteManifest instead of manually marshalling CBOR.

Name

CBOR: name; JSON: name; type: string; required: yes

Name is the stable plugin identifier, without the “restish-” executable prefix.

Plugin Messages

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

Restish v2 plugins communicate over structured messages. Operators usually need plugin debug; authors need the message families and lifecycle rules.

All startup and runtime messages are CBOR data items on stdin/stdout. CBOR is self-delimiting, so there is no length prefix or line framing. Startup discovery writes a single message and exits. Command plugins and TLS signer plugins keep one decoder open for the process lifetime because later messages can already be buffered.

Embedding Restish in Go

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

Restish can be used as a Go library when an organization wants to ship a branded CLI while keeping Restish’s request pipeline, OpenAPI command generation, auth, output, and plugin behavior.

Use out-of-process plugins for the stock restish binary. Use embedding when you own the binary and need in-process defaults or extensions.

Minimal Custom CLI

package main

import (
	"os"

	restish "github.com/rest-sh/restish/v2"
)

func main() {
	cli := restish.New()
	if err := cli.Run(os.Args); err != nil {
		cli.HandleError(err)
	}
}

Run installs SIGINT/SIGTERM handling by default so Ctrl-C cancels in-flight requests in the stock CLI. If your application already owns process signal handling, disable Restish’s handler before running: