Getting Started on Restish

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.

Install

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

This page documents the Restish v2 install path. Homebrew is the recommended managed install path for most macOS users. Build from source when you are developing Restish itself or testing changes before they are released.

Always verify the major version after installation:

restish --version

Homebrew

Use Homebrew for the easiest managed install on macOS:

brew install rest-sh/tap/restish
restish --version

The tap also keeps a legacy restish@1 formula available for users who intentionally stay on v1 during migration.

Shell Setup

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

Restish uses characters that shells also care about: ?, &, [, ], *, quotes, and spaces. Shell setup prevents the shell from rewriting request URLs, query strings, filters, and shorthand before Restish can parse them.

Configure The Wrapper

Run the setup command for your shell:

restish shell setup zsh
restish shell setup bash
restish shell setup fish

For zsh and fish, setup installs completion by default. Opt out when you only want the wrapper:

Connect to an API

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

Use generic URL requests for exploration. Register an API when you want named commands, generated help, shell completion, profiles, and auth tied to a stable short name.

Register The Example API

restish api connect example api.rest.sh

Restish discovers https://api.rest.sh/openapi.json, stores the API config, and caches the spec so generated commands are available quickly.

The API name becomes a command group. Use a name that starts with a Unicode letter or number and then uses only letters, numbers, combining marks, -, or _. Names cannot collide with built-in commands such as api, get, or post.

Upgrade From v1

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

This page is the shortest path for existing Restish v1 users who want to know what changed, what is preserved automatically, and what needs a manual update. The archived v1 documentation remains available at rest.sh/v1/ for old links, internal runbooks, and side-by-side migration checks.

What To Expect

Restish v2 keeps the same basic idea: start with generic HTTP requests, then register APIs for generated commands, profiles, auth, filtering, pagination, and plugins.

Set Up Profiles

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

Profiles are named request defaults under an API. Use them when a command should stay readable even though the target environment, auth, headers, query params, or TLS settings change.

Start With One API

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

Add profiles under the API with api set:

restish api set example 'profiles.json.headers[]: "Accept: application/json"'
restish api set example \
 'profiles.debug: {headers: ["Accept: application/json", "X-Debug: true"], query: ["trace=docs"]}'
restish api set example \
 'profiles.token.auth: {type: bearer, params: {token: env:RESTISH_DOCS_TOKEN}}'

Those commands write profile entries like this: