Plugins on Restish

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:

Built-In Example Plugins

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

The repository includes plugin binaries that are both useful tools and reference implementations. Operators can use these to try real plugin behavior. Authors can read them to see the smallest practical shape for each plugin category.

If you are only trying to install and run a plugin, start with Install and Use Plugins. If you are writing one, read the relevant author guide after finding the closest example here.

Operator-Facing Plugins

Plugin	Path	Use it for
`restish-csv`	`cmd/restish-csv/main.go`	Render array responses as CSV.
`restish-bulk`	`cmd/restish-bulk/main.go`	Manage API collections as local files.
`restish-mcp`	`cmd/restish-mcp/main.go`	Serve registered APIs as MCP tools.
`restish-pkcs11`	`cmd/restish-pkcs11/main.go`	Sign mTLS handshakes with PKCS#11-backed keys.

These binaries are built like normal Go commands. Once installed where Restish can discover them, they participate in the same plugin lifecycle as third-party plugins.

Plugin Quickstart

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

This author-focused quickstart is for plugin developers. Operators should start with Install and Use Plugins.

The quickest way to write a plugin is to start from a working first-party plugin, verify the manifest and message flow with plugin debug, and then change one capability at a time.

Author Path

Choose the smallest plugin type for the job.
Build and install a known-good plugin locally.
Verify discovery with plugin list.
Inspect protocol messages with plugin debug.
Change the manifest and implementation.
Re-run the same discovery and behavior checks.

Choose A Plugin Type

Formatter hook: easiest way to add an output format.
Loader hook: add support for an API description format or source that Restish does not load natively.
Auth hook: integrate a local credential source that should participate in Restish’s normal request pipeline.
Request or response middleware: inspect or mutate prepared requests or interpreted responses.
Command plugin: add a top-level workflow such as bulk or mcp.
TLS signer: sign mTLS handshakes when the private key must stay outside Restish.

Choose a hook when the plugin should do one focused job inside a request. Choose a command plugin when the plugin owns a multi-step workflow and needs host messages such as delegated HTTP, prompts, config reads, or formatted responses.

Hook Plugins

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

Hook plugins are short-lived extensions. Restish starts them for one focused job, reads the result, and continues the host request pipeline.

Hook Types

auth: produce or mutate request auth.
request-middleware: inspect or mutate outgoing requests.
response-middleware: inspect or mutate incoming responses.
loader: load API descriptions from additional content types or sources.
formatter: render normalized responses as new output formats.

Formatter Example

A CSV formatter should receive normalized response data and return terminal or file output without owning HTTP, auth, retry, cache, or TLS behavior.

Command Plugins

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

Command plugins add root commands such as bulk and mcp. They can perform multi-step workflows while delegating HTTP, config, prompts, and output back to Restish.

When To Use One

Use a command plugin when a feature needs:

a top-level command
multiple HTTP requests
progress messages
prompts or confirmations
access to registered APIs and profiles

Use a hook plugin for one request/response/auth/formatting task.

Delegated HTTP

Go command plugins should use plugin.CommandClient helpers instead of hand-writing CBOR messages. Delegated HTTP uses Do:

TLS Signer Plugins

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

TLS signer plugins are for mTLS environments where the client private key lives in hardware, a secure service, or another process.

Operator Example

restish \
 --rsh-tls-signer pkcs11 \
 --rsh-tls-signer-param module=/usr/local/lib/opensc-pkcs11.so \
 https://mtls.internal.test/items

Prerequisites: the signer plugin is installed, the signer can access the client certificate and signing key material it needs, and the target API requires mTLS.

Profile Shape

{
 "apis": {
 "secure": {
 "base_url": "https://mtls.internal.test",
 "profiles": {
 "default": {
 "ca_cert": "/etc/ssl/internal-ca.pem",
 "tls_signer": "pkcs11",
 "tls_signer_params": {
 "module": "/usr/local/lib/opensc-pkcs11.so",
 "token_label": "Restish",
 "pin_env": "PKCS11_PIN"
 }
 }
 }
 }
 }
}

Profile-level TLS settings override API-level defaults for that profile. Use either client_cert/client_key files or tls_signer for one request; Restish rejects configs that combine both client-certificate files and a TLS signer.

Bulk Management

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

restish bulk is a command-plugin workflow for checking out many API resources to disk, editing them locally, and pushing changes back through Restish.

Prerequisites

The restish-bulk plugin binary is installed and discoverable.
The target API exposes collection and item URLs.
You understand the API’s update semantics before pushing changes.

Verify discovery:

restish plugin list
restish bulk --help

Initialize A Checkout

The example API has a books collection used for bulk examples:

Serve APIs Over MCP

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

restish-mcp is a command plugin that exposes registered OpenAPI operations as MCP tools. Use it when an MCP client should call APIs through Restish profiles, auth, TLS, retries, and output normalization.

Prerequisites

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

The API must be registered and have a usable spec.

Serve Tools

restish mcp serve example

The plugin reads the registered API spec, turns operations into MCP tools, and delegates HTTP execution back to Restish.