DOCSEARCHbyAlgolia
Submit Docs

Restish Documentation

repository·main·Indexed 23 days ago

https://github.com/rest-sh/restish

A CLI tool for interacting with REST-ish HTTP APIs featuring dynamic command generation via OpenAPI discovery, structured output rendering (JSON, YAML, tables), and advanced authentication. The documentation covers v2 design records, embedding Restish into custom CLIs, plugin development (bulk, CSV, MCP, PKCS#11), and response filtering using jq syntax.

Tokens
151.5K
Snippets
385
Records
834
Agent score
79%

What's inside Restish

  1. Overview of Restish v2 Design Records

    main

    The Restish v2 Design Records corpus is a collection of technical specifications and design decisions that define the behavior, architecture, and implementation contracts of Restish v2. This corpus serves as the single source of truth for interoperability, security, and user expectations, ensuring that implementation details (like request execution, plugin lifecycles, and response normalization) are explicitly documented rather than implicit in the code.

    Key areas covered by these records include:

    • Foundations: CLI architecture, configuration models, and security trust boundaries.
    • Request & API Model: Authentication flows, TLS handling, OpenAPI spec discovery, and command generation.
    • Response & Data Flow: Response normalization, filtering (jq), pagination, streaming (SSE/NDJSON), and caching.
    • Workflows & UX: Edit workflows, shell completions, diagnostics, and specialized output formats like TOON for LLM agents.
    • Extensibility: Plugin architectures (hook, command, and TLS-signer plugins) and custom CLI embedding surfaces.

  2. What is Restish?

    main

    Restish is a CLI designed for interacting with REST-ish HTTP APIs. Its core philosophy is that the API server should define the interface, allowing the CLI to stay up-to-date with the latest operations and schemas via OpenAPI 3 specifications without requiring client updates.

    Key Capabilities:

    • Generic HTTP Verbs: Perform quick one-off requests similar to curl or HTTPie.
    • Generated Commands: Automatically creates documented, shell-completed commands for registered OpenAPI APIs.
    • Automatic Updates: Fetches and caches API descriptions automatically.
    • Hypermedia Support: First-class support for navigating link-driven APIs.
    • Embeddable: Can be used as a Go library to build custom CLIs.

  3. Overview of Restish

    main
    Restish is a CLI tool designed for interacting with REST-ish HTTP APIs. Unlike traditional tools like curl or HTTPie that require manual command construction, Restish leverages API hypermedia and descriptions to provide a dynamic interface. It automatically discovers API resources, fields, and operations as they become available on the server, meaning the CLI stays up-to-date without requiring manual updates or re-installs.

  4. Explore Restish Data and Configuration Reference

    main

    The Data and Configuration Reference covers how Restish handles persistent settings, data formats, and input syntax:

    Configuration and Credentials

    • Config: Persistent settings.
    • Profiles: Configuration profiles.
    • Auth: Authentication settings and credentials.
    • Environment Variables: Overrides for configuration via environment variables.

    Data Handling and Syntax

    • Content Types: Request encoding and response decoding.
    • Output: Default rendering and available output formats.
    • Input and Filtering: Shorthand syntax and query syntax for filters.
    • Example API: Live documentation fixtures.

    Extensions

    • Embedding: Information on building custom Go CLIs using Restish.

  6. Explore the Restish Command and Flag Reference

    main

    The Command and Flag Reference provides a factual lookup for the Restish CLI surface. Use these resources to find specific command behaviors, global flags, and specialized management tools:

    Commands

    • Commands: Top-level command surface.
    • HTTP Commands: Generic verbs and bare URL method inference.
    • Global Flags: Shared flags for requests, output, authentication, TLS, pagination, cache, retry, and configuration.
    • API Management: Commands under the restish api ... namespace.
    • Support Commands: Includes config, cache, doctor, shell, and various utilities.
    • Specialized Commands: edit, plugin, bulk, and openapi (for OpenAPI CLI integration and extensions).

  7. Compare Restish features with cURL and HTTPie

    main

    Restish is a Go-based CLI tool designed for API interaction with several advanced features compared to cURL and HTTPie:

    • Protocol & Encoding: Supports HTTPS and HTTP/2 by default. Includes support for gzip and brotli encoding, as well as CBOR and MessagePack binary format decoding.
    • Authentication: Provides native OAuth2.0 token fetching/caching and authentication profiles.
    • Data Handling: Supports content negotiation by default, shorthand for structured data input, and loading fields from files using the @ prefix. It also supports raw input via stdin.
    • API Intelligence: Features API nicknames (e.g., github/users/repos), OpenAPI 3 support, automatic pagination for next link relations, and hypermedia link parsing.
    • Developer Experience: Provides API documentation and examples via --help, syntax highlighting, pretty printing, image response previews in the terminal, and structured response filtering.

  9. Common Restish workflows

    main

    Restish supports several core workflows for interacting with APIs:

    • Making Requests: Use generic HTTP verbs or use generated commands from an OpenAPI spec.
    • Sending Request Bodies: Use shorthand, stdin, forms, or multipart uploads.
    • Shaping Output: Control how data is presented using formats, filters, tables, raw bytes, or files.
    • Pagination: Follow links and pagination markers across collections.
    • Streaming: Stream events from Server-Sent Events (SSE) and NDJSON endpoints.
    • Troubleshooting: Use symptom-driven fixes to resolve behavior issues.

  10. Use the restish-bulk plugin for bulk data workflows

    main

    restish-bulk is a command plugin designed for workflows where you need to pull a collection of remote API resources down to your local machine, edit them, and push them back in a controlled manner. It is ideal for repeatable content maintenance or data tasks that are too slow or error-prone to perform one request at a time.

    Workflow Pattern:

    1. Initialize: Start a workspace using init on a list endpoint.
    2. Inspect: Use status to check for changes and diff to preview edits.
    3. Sync: Use pull to refresh local data or push to upload changes.
    4. Cleanup: Use reset to discard local changes and return to a clean state.

    Note: Before using the plugin, verify it is discovered by running restish plugin list.

    restish bulk init api.rest.sh/books
restish bulk status
restish bulk pull
restish bulk diff
restish bulk push
restish bulk reset

  11. Explore Restish Workflow Guides

    main

    Restish provides several task-oriented guides categorized by workflow. Use these guides to understand how to combine multiple commands to achieve a goal.

    Core Request Workflows

    • Requests: Learn about generic URLs, generated commands, headers, query parameters, and debugging.
    • Authentication: Manage basic auth, bearer tokens, API keys, and integration with external tools.
    • OAuth: Handle client credentials, browser sign-in, device code, token caching, and provider-specific setups.
    • Input and Shorthand: Work with request bodies, stdin, forms, and file uploads.
    • Output: Configure auto output, JSON, NDJSON, tables, raw bytes, and file output.

    Advanced Workflows

    • Data Handling: Pagination, Links and Hypermedia, Filtering, and Streaming.
    • Reliability and Automation: Retries, Caching, Command Behavior, and Scripting/Automation.
    • API Integration: API Setup and Discovery, and OpenAPI CLI integration.
    • Environment and Setup: TLS, Shell Setup, Edit Workflow, and using the doctor command for diagnostics.

  12. Understand plugin lifecycle expectations in Restish

    main

    When developing or using plugins in Restish, you should adhere to several universal lifecycle rules to ensure system stability and debuggability:

    • Host Ownership: All plugin processes are tied to a host-owned context.
    • Error Reporting: The host surfaces plugin stderr when useful for debugging. If stderr shares a destination with host diagnostics, it should be serialized by line.
    • Timeouts: The host is designed not to wait indefinitely for a hung plugin.
    • Cleanup: Even upon successful completion, plugins must ensure proper process cleanup.
    • Performance: Per-request hook plugins are expected to start in under 100 ms. Any expensive initialization or heavy work should be moved to command plugins or a long-lived hook design to avoid blocking the request pipeline.