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.

Development Setup

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

Use this page when changing code, plugins, or docs in the Restish repository.

Build The CLI

go build ./cmd/restish

Build Plugin Binaries

go build ./cmd/restish-bulk
go build ./cmd/restish-csv
go build ./cmd/restish-mcp
go build ./cmd/restish-pkcs11

Run Tests

go test ./...
go test ./internal/cli/...

Run the integration-tag suite before commits that touch CLI or plugin behavior:

go test -tags=integration ./...

Use a temporary GOCACHE when your environment needs an isolated cache:

GOCACHE=/tmp/restish-gocache go test ./...

Update Golden Files

go test -update ./internal/output/...

Build The Docs Site

go run ./cmd/restish-docgen --check
hugo --source site --quiet
scripts/check-doc-links.rb

When command help, global flags, plugin protocol structs, or built-in command plugins change, refresh the checked-in generated regions first:

Install and Use Plugins

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

This is the operator path for using plugins that already exist.

Plugins are executable programs on your machine. Install and run them at your own risk, from sources you trust. Restish checks the plugin manifest and capabilities, but it does not sandbox plugin code or verify publisher identity.

List Plugins

restish plugin list

Run this first when an output format, command, auth method, or TLS signer is missing.

Install A Plugin

Install from the official Restish GitHub releases:

Requests

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

Restish supports two request styles: generic HTTP requests for immediate access and API-aware commands generated from an API description for repeated work.

Start With A Generic Request

Browser preview

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

Ready

restish api.rest.sh/get

Enable JavaScript to run this example in the browser.

Tour of Restish

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

This tour shows the shape of Restish before you commit to a local setup. You can run the examples in your browser against the live docs API at https://api.rest.sh, edit the commands, and then use the same commands in a terminal after installing Restish.

Restish is an API-aware HTTP CLI. It works as a direct request tool when you have only a URL, and it can also learn an API from OpenAPI so repeated work gets generated commands, auth, profiles, completions, filtering, pagination, and output formats.

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.

API Setup and Discovery

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

Restish can call any URL, but registering an API gives you generated commands, profiles, auth setup, spec caching, and completion.

Configure By Discovery

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

Restish looks for an OpenAPI description through well-known locations and link relations, then caches the spec.

Discovery is intentionally conservative. Restish trusts same-origin spec links by default; use --allow-cross-origin-spec only when you expect the API to advertise its OpenAPI document from another host and you trust that host. Cross-origin discovery still rejects private, loopback, link-local, multicast, and unspecified follow targets unless the original API is already private or local. Use --spec when you need to name a private spec URL directly.

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.

Authentication

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

Auth belongs with the request context. In Restish that usually means a profile, so tokens, API keys, and environment-specific credentials do not get copied into every command.

Safe Auth Fixtures

The example API has endpoints that require auth and return only a safe summary. They are useful for learning and testing.

Bearer Token

Browser preview

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

Ready

restish -H 'Authorization: Bearer docs-token' api.rest.sh/auth/bearer --rsh-print b