README
¶
Restish
Restish is a CLI for working with REST-ish HTTP APIs. It can make generic HTTP requests, discover OpenAPI descriptions, generate API-aware commands, manage profiles and auth, render structured output, follow pagination links, and run plugins.
Restish v2 is the active release line. Users who need the legacy v1 line can
install rest-sh/tap/restish@1; see the
v1 upgrade guide.
Try It
Make a direct request with no setup beyond installing the CLI:
restish api.rest.sh/types
Then format, filter, and page through real API responses:
restish api.rest.sh/images -o table --rsh-columns name,format,self
restish api.rest.sh/example -f 'body.basics.{name,url,profiles}'
Example table output:
name format self
Dragonfly macro jpeg /images/jpeg
Origami under blacklight webp /images/webp
Andy Warhol mural in Miami gif /images/gif
Install
Use Homebrew for the easiest managed install on macOS:
brew install rest-sh/tap/restish
restish --version
Or use mise:
mise use -g restish@latest
restish --version
Install the latest tagged v2 release from source with Go:
go install github.com/rest-sh/restish/v2/cmd/restish@latest
restish --help
Check restish --version after installation. See the
install guide for shell setup,
upgrades, and platform notes.
Why Restish?
- Use one-off HTTP commands with good defaults for headers, content types, retries, caching, TLS, and output.
- Connect OpenAPI descriptions to get generated API commands, help, profiles, auth, and shell completion.
- Filter normalized responses with shorthand or jq, then render JSON, YAML, tables, CSV, NDJSON, lines, gron, images, and raw downloads.
- Follow pagination links and stream API data without writing boilerplate loops.
- Extend the CLI with plugins for bulk workflows, CSV, MCP, TLS signing, and custom API behavior.
Documentation
Plugins
Bundled plugins live in this repository and can be built alongside the main CLI:
go build ./cmd/restish-bulk
go build ./cmd/restish-csv
go build ./cmd/restish-mcp
go build ./cmd/restish-pkcs11
Start with Install and Use Plugins or Plugin Quickstart.
Development
Build from this repository when developing Restish itself:
go build ./cmd/restish
./restish --help
./restish api.rest.sh/types
Run the normal development loop with:
go test ./...
Build the CLI and bundled plugins with:
go build ./cmd/restish
go build ./cmd/restish-bulk
go build ./cmd/restish-csv
go build ./cmd/restish-mcp
go build ./cmd/restish-pkcs11
Run the full integration suite before releases or larger CLI/plugin changes:
go test -tags=integration ./...
Development docs:
License
Restish is released under the MIT License. See LICENSE.md.
Documentation
¶
Overview ¶
Package restish is the public Go API for embedding Restish in custom CLIs.
The stock restish binary is built from cmd/restish. Embedders can construct a CLI directly, register organization-specific auth handlers, content types, encodings, link parsers, OpenAPI loaders, and formatters, then call Run with their own argv.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type APIConfig ¶
APIConfig holds one registered API's base URL, spec source, profiles, and generated-command options.
type AuthConfig ¶
type AuthConfig = config.AuthConfig
AuthConfig holds one configured auth handler type and its parameters.
type AuthContext ¶
type AuthContext = auth.AuthContext
AuthContext is passed to custom auth handlers during request authentication.
type AuthHandler ¶
AuthHandler is implemented by custom authentication schemes.
type CLI ¶
type CLI = internalcli.CLI
CLI is an embeddable Restish runtime.
The zero value is not intended for use; call New so standard content types, loaders, formatters, paths, and I/O streams are initialized.
func New ¶
func New() *CLI
New returns a CLI wired to the real OS stdin/stdout/stderr and the default Restish registries. Customize it with SetCommandName, SetCommandDescription, SetVersion, SetSignalHandling, SetDefaultConfig, AddAuthHandler, AddContentType, AddEncoding, AddLinkParser, AddLoader, and AddFormatter before calling Run.
type ContentType ¶
type ContentType = content.ContentType
ContentType describes one request/response body encoder and decoder.
type Link ¶
type Link = hypermedia.Link
Link is a normalized hypermedia link returned by custom link parsers.
type LinkParser ¶
type LinkParser = hypermedia.Parser
LinkParser extracts hypermedia links from response headers or bodies.
type LoadOptions ¶
type LoadOptions = spec.LoadOptions
LoadOptions carries source metadata for custom spec loaders.
type ProfileConfig ¶
type ProfileConfig = config.ProfileConfig
ProfileConfig holds one API profile's headers, query parameters, auth, and TLS settings.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
restish
command
|
|
|
restish-bulk
command
|
|
|
restish-csv
command
|
|
|
restish-docgen
command
|
|
|
restish-mcp
command
|
|
|
restish-pkcs11
command
|
|
|
internal
|
|
|
cache
Package cache provides a size-bounded, LRU-evicting disk cache that implements the httpcache.Cache interface.
|
Package cache provides a size-bounded, LRU-evicting disk cache that implements the httpcache.Cache interface. |
|
content
Package content provides a registry of content types and encodings for marshalling/unmarshalling request and response bodies, and for transparent decompression of compressed responses.
|
Package content provides a registry of content types and encodings for marshalling/unmarshalling request and response bodies, and for transparent decompression of compressed responses. |
|
filter
Package filter applies shorthand or jq expressions to a response value.
|
Package filter applies shorthand or jq expressions to a response value. |
|
hypermedia
Package hypermedia provides parsers that extract typed links from HTTP responses in various hypermedia formats (Link headers, HAL, TSJ, JSON:API, Siren).
|
Package hypermedia provides parsers that extract typed links from HTTP responses in various hypermedia formats (Link headers, HAL, TSJ, JSON:API, Siren). |
|
input
Package input builds HTTP request bodies from CLI arguments and/or stdin.
|
Package input builds HTTP request bodies from CLI arguments and/or stdin. |
|
plugin
Package plugin handles discovery, manifest loading, and caching of Restish out-of-process plugins.
|
Package plugin handles discovery, manifest loading, and caching of Restish out-of-process plugins. |
|
secrets
Package secrets centralizes the small allow-lists Restish uses to recognize credential-bearing names at trust boundaries.
|
Package secrets centralizes the small allow-lists Restish uses to recognize credential-bearing names at trust boundaries. |
|
spec
Package spec handles API specification discovery, loading, and caching.
|
Package spec handles API specification discovery, loading, and caching. |
|
Package plugin provides the public contract for writing Restish out-of-process plugins.
|
Package plugin provides the public contract for writing Restish out-of-process plugins. |
|
Package themes exposes the official Restish theme files bundled with each release.
|
Package themes exposes the official Restish theme files bundled with each release. |