# rest-sh/restish architecture

> Architecture diagram of the GitHub repository rest-sh/restish, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rest-sh/restish
- Repository: https://github.com/rest-sh/restish

## Overview

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: [`cli/request.go`](https://github.com/rest-sh/restish/blob/HEAD/cli/request.go) (Request build), [`cli/cli.go`](https://github.com/rest-sh/restish/blob/HEAD/cli/cli.go) (CLI core), [`cli/transport.go`](https://github.com/rest-sh/restish/blob/HEAD/cli/transport.go) (Transport), [`cli/content.go`](https://github.com/rest-sh/restish/blob/HEAD/cli/content.go) (Content decode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "CLI Runtime"
  main["main.go<br/>entrypoint<br/>[main.go]"]
  cli_core["CLI core<br/>runtime<br/>[cli.go]"]
  cli_flags["Flags<br/>parsing<br/>[flag.go]"]
  cli_input["Input<br/>[input.go]"]
  cli_interactive["Interactive<br/>ui<br/>[interactive.go]"]
  cli_request["Request build<br/>[request.go]"]
  cli_operation["Operations<br/>command-model<br/>[operation.go]"]
  cli_param["Params<br/>command-model<br/>[param.go]"]
  cli_transport[("Transport<br/>http-client<br/>[transport.go]")]
  cli_links["Links<br/>hypermedia<br/>[links.go]"]
end

subgraph "Metadata & Auth"
  cli_auth["Auth<br/>[auth.go]"]
  cli_apiconfig["API config<br/>[apiconfig.go]"]
  openapi["OpenAPI<br/>metadata<br/>[openapi.go]"]
  oauth["OAuth<br/>token-flow<br/>[oauth.go]"]
end

subgraph "Response Output"
  cli_output["Output<br/>presentation<br/>[formatter.go]"]
  cli_content["Content decode<br/>[content.go]"]
  cli_readable["Readable<br/>format<br/>[readable.go]"]
  cli_gron["Gron<br/>format<br/>[gron.go]"]
end

subgraph "Bulk Mode"
  bulk["Bulk mode<br/>batch<br/>[commands.go]"]
end

main -->|"starts"| cli_core
cli_core -->|"parses"| cli_flags
cli_core -->|"collects"| cli_input
cli_core -->|"dispatches"| cli_operation
cli_operation -->|"binds"| cli_param
cli_param -->|"shapes"| cli_request
cli_input -->|"feeds"| cli_request
cli_interactive -->|"prompts"| cli_input
cli_request -->|"prepares"| cli_auth
cli_auth -->|"acquires"| oauth
openapi -->|"describes"| cli_operation
openapi -->|"schemas"| cli_param
cli_apiconfig -->|"configures"| cli_auth
cli_request -->|"sends"| cli_transport
cli_transport -->|"returns"| cli_output
cli_transport -->|"parses"| cli_links
cli_links -.->|"next action"| cli_request
cli_output -->|"decodes"| cli_content
cli_content -->|"renders"| cli_readable
cli_content -->|"renders"| cli_gron
bulk -->|"executes"| cli_request
bulk -->|"runs"| cli_transport

click main "https://github.com/rest-sh/restish/blob/main/main.go"
click cli_core "https://github.com/rest-sh/restish/blob/main/cli/cli.go"
click cli_flags "https://github.com/rest-sh/restish/blob/main/cli/flag.go"
click cli_input "https://github.com/rest-sh/restish/blob/main/cli/input.go"
click cli_interactive "https://github.com/rest-sh/restish/blob/main/cli/interactive.go"
click cli_request "https://github.com/rest-sh/restish/blob/main/cli/request.go"
click cli_operation "https://github.com/rest-sh/restish/blob/main/cli/operation.go"
click cli_param "https://github.com/rest-sh/restish/blob/main/cli/param.go"
click cli_transport "https://github.com/rest-sh/restish/blob/main/cli/transport.go"
click cli_output "https://github.com/rest-sh/restish/blob/main/cli/formatter.go"
click cli_content "https://github.com/rest-sh/restish/blob/main/cli/content.go"
click cli_readable "https://github.com/rest-sh/restish/blob/main/cli/readable.go"
click cli_gron "https://github.com/rest-sh/restish/blob/main/cli/gron.go"
click cli_links "https://github.com/rest-sh/restish/blob/main/cli/links.go"
click cli_auth "https://github.com/rest-sh/restish/blob/main/cli/auth.go"
click cli_apiconfig "https://github.com/rest-sh/restish/blob/main/cli/apiconfig.go"
click openapi "https://github.com/rest-sh/restish/blob/main/openapi/openapi.go"
click oauth "https://github.com/rest-sh/restish/blob/main/oauth/oauth.go"
click bulk "https://github.com/rest-sh/restish/blob/main/bulk/commands.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class main,cli_core,cli_flags,cli_input,cli_interactive,cli_request,cli_operation,cli_param,cli_transport,cli_links toneBlue
class cli_auth,cli_apiconfig,openapi,oauth toneAmber
class cli_output,cli_content,cli_readable,cli_gron toneMint
class bulk toneRose
```

## Components

### CLI Runtime

Command parsing, dispatch, request execution, and terminal I/O.

- [main.go](https://github.com/rest-sh/restish/blob/HEAD/main.go): entrypoint · Executable entrypoint. · `main.go`
- [CLI core](https://github.com/rest-sh/restish/blob/HEAD/cli/cli.go): runtime · Top-level CLI orchestration and command dispatch. · `cli/cli.go`
- [Flags](https://github.com/rest-sh/restish/blob/HEAD/cli/flag.go): parsing · Argument and flag handling. · `cli/flag.go`
- [Input](https://github.com/rest-sh/restish/blob/HEAD/cli/input.go): input · CLI, stdin, file, and interactive input collection. · `cli/input.go`
- [Interactive](https://github.com/rest-sh/restish/blob/HEAD/cli/interactive.go): ui · Prompting, editing, and other interactive behaviors. · `cli/interactive.go`
- [Request build](https://github.com/rest-sh/restish/blob/HEAD/cli/request.go): request · Builds HTTP requests from commands and inputs. · `cli/request.go`
- [Operations](https://github.com/rest-sh/restish/blob/HEAD/cli/operation.go): command-model · Generated command and operation metadata. · `cli/operation.go`
- [Params](https://github.com/rest-sh/restish/blob/HEAD/cli/param.go): command-model · Parameter shaping and binding. · `cli/param.go`
- [Transport](https://github.com/rest-sh/restish/blob/HEAD/cli/transport.go): http-client · HTTP client boundary and network exchange. · `cli/transport.go`
- [Links](https://github.com/rest-sh/restish/blob/HEAD/cli/links.go): hypermedia · Parses navigable relations from responses. · `cli/links.go`

### Metadata & Auth

API description ingestion, config, and credential preparation.

- [Auth](https://github.com/rest-sh/restish/blob/HEAD/cli/auth.go): auth · API auth orchestration and credential attachment. · `cli/auth.go`
- [API config](https://github.com/rest-sh/restish/blob/HEAD/cli/apiconfig.go): config · API-specific configuration and persistence. · `cli/apiconfig.go`
- [OpenAPI](https://github.com/rest-sh/restish/blob/HEAD/openapi/openapi.go): metadata · OpenAPI and JSON Schema ingestion and example generation. · `openapi/openapi.go`
- [OAuth](https://github.com/rest-sh/restish/blob/HEAD/oauth/oauth.go): token-flow · Token acquisition, refresh, and OAuth request helpers. · `oauth/oauth.go`

### Response Output

Decoding, formatting, and readable terminal presentation.

- [Output](https://github.com/rest-sh/restish/blob/HEAD/cli/formatter.go): presentation · Response handling and terminal output coordination. · `cli/formatter.go`
- [Content decode](https://github.com/rest-sh/restish/blob/HEAD/cli/content.go): decode · Content-type and encoding decoding. · `cli/content.go`
- [Readable](https://github.com/rest-sh/restish/blob/HEAD/cli/readable.go): format · Colorized human-readable rendering. · `cli/readable.go`
- [Gron](https://github.com/rest-sh/restish/blob/HEAD/cli/gron.go): format · Flattened gron-style output. · `cli/gron.go`

### Bulk Mode

Filesystem-driven batch execution path.

- [Bulk mode](https://github.com/rest-sh/restish/blob/HEAD/bulk/commands.go): batch · Batch command execution from files and metadata. · `bulk/commands.go`

## Connections

- 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.
