How rest-sh/restish works
Restish is a single Go CLI binary that sits between a user and one or more HTTP APIs. Its architecture is organized around a command-processing pipeline with a few clear subsystems:
1. CLI entrypoint and orchestration
- main.go is the executable entrypoint.
- The cli package is the core runtime layer. It owns:
- argument/flag parsing
- command dispatch
- request construction
- response handling
- logging and terminal output
- interactive behaviors like prompting and editing
- This layer is the main integration boundary where all other packages come together.
2. API invocation layer
- The CLI supports both:
- generic HTTP verbs like GET/POST/PUT/PATCH/DELETE
- generated API commands derived from API descriptions and hypermedia metadata
- Command execution flows through request-building code in cli/request.go, cli/operation.go, cli/param.go, and related helpers.
- Inputs can come from:
- command-line arguments
- shorthand structured input
- files/stdin
- interactive prompts
- The request layer turns those inputs into an HTTP request, then sends it through the transport layer.
3. Transport and network boundary
- cli/transport.go is the HTTP client boundary.
- The runtime talks to external systems over HTTP/HTTPS, with HTTP/2 preferred and HTTP/1.1 fallback per the README.
- This is where retries, caching behavior, content encodings, and response handling are applied around the raw network exchange.
- External dependencies at this boundary include:
- target REST-ish APIs
- OAuth token endpoints
- any external authorization/signing tools used for custom auth
4. Authentication subsystem
- Auth logic is split across cli/auth.go, cli/api.go, cli/apiconfig.go, and the oauth package.
- The oauth package implements token acquisition flows:
- authorization code
- client credentials
- refresh handling
- OAuth request helpers
- The auth subsystem is used to automatically configure API authentication when an API advertises auth metadata, and to attach credentials to outgoing requests.
- This is a distinct boundary from request execution: auth is prepared before the request is sent, then injected into the transport/request path.
5. API discovery and OpenAPI/schema processing
- The openapi package is responsible for interpreting API descriptions and schema material.
- It handles OpenAPI and JSON Schema artifacts, example generation, and schema parsing.
- The README indicates Restish can auto-discover API descriptions via hypermedia relations such as service-desc and describedby.
- This subsystem feeds the CLI with:
- command/operation metadata
- parameter and body shapes
- examples
- auto-configuration hints
- In the architecture diagram, this is the “API metadata ingestion” layer that informs how commands are rendered and requests are shaped.
6. Content decoding, formatting, and response presentation
- The cli/content.go, cli/encoding.go, cli/formatter.go, cli/readable.go, and cli/gron.go files indicate a presentation pipeline for responses.
- Restish decodes multiple content types and encodings described in the README:
- JSON, YAML, CBOR, MessagePack, Amazon Ion
- gzip, deflate, brotli encodings
- Response data is then formatted for terminal output, including:
- colorized readable rendering
- shorthand/query-based projection/filtering
- gron-style flattened output
- This layer is important because it separates raw HTTP response bytes from user-facing terminal output.
7. Hypermedia and navigation support
- cli/links.go and the README’s hypermedia features show that Restish can parse and follow response links.
- Supported relation sources include:
- HTTP Link headers
- HAL
- Siren
- JSON:API
- other hypermedia conventions noted in the README
- This subsystem provides discovery/navigation capabilities on top of ordinary request/response handling.
- In a diagram, it sits between response parsing and the next request selection path.
8. Bulk execution subsystem
- The bulk package is a separate execution path for issuing multiple operations from file-based inputs.
- Based on file names like commands.go, file.go, and metadata.go, it likely maps batch files and associated metadata into repeated CLI operations.
- This is a distinct input mode from single-command interactive use and should be shown as a filesystem-driven batch branch feeding the same request/transport core.
9. Configuration and command generation support
- cli/autoconfig.go, cli/apiconfig.go, and related files suggest a configuration layer that persists or derives API-specific settings.
- This includes endpoint-specific configuration, auth profiles, and likely command completion/command shaping support.
- The project also supports shell completions, so there is a CLI metadata/export path separate from request execution.
10. Runtime I/O boundaries
- Inbound: terminal arguments, stdin, files, API descriptions, and OAuth/provider metadata
- Outbound: HTTP requests, OAuth requests, terminal output, stderr logs, and possibly cached local state/config
- The repo is fundamentally a local client application; it does not expose a server runtime.
End-to-end data flow
A typical request path is:
• User runs the CLI with a verb or generated operation
• CLI resolves the command and collects parameters/body input
• If needed, the app discovers API metadata from an OpenAPI/schema or hypermedia source
• Auth is resolved or refreshed
• Request is built and sent through the transport
• Response is decoded, optionally retried/paginated, then formatted for terminal output
• If the response exposes navigable links, the next action can be derived from those links
Important architectural boundaries to draw
For an architecture diagram, the key boundaries are:
• User/terminal boundary: command input and formatted output
• Metadata boundary: OpenAPI/hypermedia discovery feeds command generation
• Auth boundary: OAuth and API auth are separate from core request execution
• Network boundary: transport to external REST APIs and OAuth servers
• Filesystem boundary: batch inputs, local config, and generated/tested assets
Non-runtime supporting areas
• .github/workflows and .goreleaser.yml define CI and release automation.
• docs/ is the published user documentation site.
• *_test.go files and test data directories show the repo is heavily test-driven, with fixtures for OpenAPI parsing and CLI behavior.
• These support the product but are not part of the runtime architecture.
Overall, Restish is best understood as a layered CLI client: a command/UI layer on top of request construction, with separate subsystems for API discovery, auth, transport, response decoding, and presentation.
Main entry points: request.go Request build · cli.go CLI core · transport.go Transport · content.go Content decode
Components 19
CLI Runtime
Command parsing, dispatch, request execution, and terminal I/O.
- main.go · Executable entrypoint.
main.go - CLI core · Top-level CLI orchestration and command dispatch.
cli/cli.go - Flags · Argument and flag handling.
cli/flag.go - Input · CLI, stdin, file, and interactive input collection.
cli/input.go - Interactive · Prompting, editing, and other interactive behaviors.
cli/interactive.go - Request build · Builds HTTP requests from commands and inputs.
cli/request.go - Operations · Generated command and operation metadata.
cli/operation.go - Params · Parameter shaping and binding.
cli/param.go - Transport · HTTP client boundary and network exchange.
cli/transport.go - Links · Parses navigable relations from responses.
cli/links.go
Metadata & Auth
API description ingestion, config, and credential preparation.
- Auth · API auth orchestration and credential attachment.
cli/auth.go - API config · API-specific configuration and persistence.
cli/apiconfig.go - OpenAPI · OpenAPI and JSON Schema ingestion and example generation.
openapi/openapi.go - OAuth · Token acquisition, refresh, and OAuth request helpers.
oauth/oauth.go
Response Output
Decoding, formatting, and readable terminal presentation.
- Output · Response handling and terminal output coordination.
cli/formatter.go - Content decode · Content-type and encoding decoding.
cli/content.go - Readable · Colorized human-readable rendering.
cli/readable.go - Gron · Flattened gron-style output.
cli/gron.go
Bulk Mode
Filesystem-driven batch execution path.
- Bulk mode · Batch command execution from files and metadata.
bulk/commands.go
Connections 22
- main.go → CLI core: starts · Executable hands off to the CLI runtime.
- CLI core → Flags: parses · CLI resolves arguments and flags before dispatch.
- CLI core → Input: collects · Command execution gathers input from files, stdin, or prompts.
- CLI core → Operations: dispatches · Resolves the command or generated operation.
- Operations → Params: binds · Operation metadata drives parameter binding.
- Params → Request build: shapes · Parameters are transformed into request inputs.
- Input → Request build: feeds · Raw user input is incorporated into the request.
- Interactive → Input: prompts · Interactive editing and prompting supply structured input.
- Request build → Auth: prepares · Request construction consults auth configuration and credentials.
- Auth → OAuth: acquires · OAuth flows obtain and refresh access tokens.
- OpenAPI → Operations: describes · API descriptions generate command and operation metadata.
- OpenAPI → Params: schemas · Schema material informs parameter and body shapes.
- API config → Auth: configures · API-specific settings influence auth setup.
- Request build → Transport: sends · Built requests are sent through the HTTP boundary.
- Transport → Output: returns · Responses flow into response handling and presentation.
- Transport → Links: parses · Response metadata is examined for navigable links.
- Links → Request build: next action · Discovered links can drive the next request selection.
- Output → Content decode: decodes · Raw response bodies are decoded by content type and encoding.
- Content decode → Readable: renders · Decoded data can be rendered in readable form.
- Content decode → Gron: renders · Decoded data can be rendered as flattened output.
- Bulk mode → Request build: executes · Batch files map into repeated request execution.
- Bulk mode → Transport: runs · Bulk mode still uses the shared transport boundary.