Config

Restish config is the trust boundary for API base URLs, generated command sources, profiles, auth, TLS, plugins, cache settings, and terminal-output themes.

Location And Selection

Default config lives in a Restish config directory as restish.json:

Config path precedence:

1. --rsh-config <file>
2. RSH_CONFIG=<file>
3. RSH_CONFIG_DIR=<dir>/restish.json
4. XDG_CONFIG_HOME/restish/restish.json
5. platform default

restish --rsh-config ./restish.json api list
RSH_CONFIG=./restish.json restish api list

An explicit config file is the whole source of truth for that invocation. If it is missing, Restish errors instead of falling back to user config.

If no default config directory can be determined, set RSH_CONFIG or RSH_CONFIG_DIR. Restish does not create a relative ./.restish directory. Cache-only state may use a temporary directory until RSH_CACHE_DIR or XDG_CACHE_HOME is available.

When no explicit config is selected, Restish searches the current directory and parents for .restish.json. A discovered project config is ignored until you trust it:

restish config trust

Trust is stored outside the repository and includes the file’s content hash. If .restish.json changes, run restish config trust again after reviewing it. Trusted project config layers apis and theme over your global config. Project APIs override global APIs with the same name, while unrelated global APIs remain available. Normal config-writing commands still write the global config and refuse to mutate APIs that came from trusted project config.

Project config is safe to commit when it contains only shared, non-secret setup. Secret auth params such as API key values, bearer tokens, passwords, and OAuth client secrets must be omitted or written as env:NAME references. Non-secret values such as OAuth client_id, audience, issuer URLs, token URLs, and scopes can live in .restish.json.

Use --rsh-config ./.restish.json or RSH_CONFIG=./.restish.json when a command should use one complete project config file instead of layering trusted project config over the global config. Explicit config selection can point to any filename; .restish.json is only the auto-discovered project filename.

On Unix-like systems, Restish refuses group/world-readable config files because profiles and auth settings may contain secrets:

chmod 600 ~/.config/restish/restish.json

Inspect the active config:

restish config path
restish config show
restish config show -o json

Example Shape

{
  "apis": {},
  "auth_profiles": {},
  "cache": {},
  "theme_source": "https://example.com/theme.json",
  "theme": {},
  "plugins": {}
}

API Entries

{
  "apis": {
    "example": {
      "base_url": "https://api.rest.sh",
      "spec_url": "https://api.rest.sh/openapi.json",
      "allow_cross_origin_spec": false,
      "spec_files": [],
      "operation_base": "/",
      "command_layout": "flat",
      "server_variables": {},
      "url_overrides": {
        "https://api.vendor.test/": "https://staging.vendor.test/"
      },
      "allowed_operation_origins": [],
      "retry_max_wait": "30s",
      "pagination": {
        "items_path": "data",
        "next_path": "links.next",
        "page_param": "page"
      },
      "profiles": {
        "default": {},
        "json": { "headers": ["Accept: application/json"] }
      }
    }
  }
}

API names may contain Unicode letters, Unicode numbers, combining marks, -, and _, and must start with a letter or number. They cannot collide with built-in commands such as api, get, or post, or hidden compatibility commands such as completion. Removed commands are not reserved; flags is a valid API name in v2.

Fields

Generated from internal/config/config.go.

Config

Config is the top-level configuration for Restish, loaded from restish.json.

APIConfig

APIConfig holds per-API configuration.

PaginationConfig

PaginationConfig holds per-API pagination settings.

CacheConfig

CacheConfig holds cache settings.

AuthConfig

AuthConfig holds authentication configuration for a profile.

Profiles

Profiles hold request defaults under an API. See Profiles for the full field reference.

{
  "profiles": {
    "default": {},
    "staging": {
      "base_url": "https://staging.example.com",
      "headers": ["Accept: application/json"],
      "query": ["trace=docs"],
      "auth": {
        "type": "bearer",
        "params": {
          "token": "env:EXAMPLE_TOKEN"
        }
      }
    }
  }
}

Auth Profiles

Use top-level auth_profiles when several APIs or profiles should share one credential configuration:

{
  "auth_profiles": {
    "work-user-oauth": {
      "type": "oauth-authorization-code",
      "params": {
        "authorize_url": "https://issuer.test/authorize",
        "token_url": "https://issuer.test/oauth/token",
        "client_id": "env:CLIENT_ID",
        "scopes": "read:items",
        "redirect_path": "/callback"
      }
    }
  }
}

Profiles can reference these with auth_ref.

Secret params may use env:NAME or command:.... Command secrets and external-tool auth snippets run through cmd /c on Windows and /bin/sh -c elsewhere.

Cache

Cache settings control the HTTP response cache, not OAuth/auth token cache. Use restish cache info to inspect runtime cache location, size, entry count, oldest entry, largest cached hosts, and API/profile cache usage. Restish does not write cache entries for responses that carry credential-bearing headers such as Set-Cookie or common API-key headers.

restish config set 'cache.max_size: 250MB'
restish cache info
restish cache clear

Use restish api auth logout for cached auth tokens.

Theme

Themes affect auto terminal output and printed HTTP transcript highlighting. Theme files may be JSON or JSONC:

restish config theme list
restish config theme set one-dark-pro
restish config theme set restish-dark
restish config theme set ./theme.json
restish config theme set user/repo dark --yes
restish config theme reset

theme_source records where the theme came from. Local paths are stored as absolute paths, and bundled official themes are stored as official:<name>. theme stores the resolved highlighting values. Use text for the base text color, header_key to color HTTP response header names differently from JSON object keys, heading for interactive help headings, and diagnostic_warn, diagnostic_error, diagnostic_hint, or status_2xx to customize human status output. reset removes the saved theme and restores the built-in theme; setting restish-dark does the same thing.

For GitHub shorthand with a theme name, Restish tries themes/<name>.json first, then falls back to <name>.json at the repository root. Name-only theme installation uses the official themes bundled with the Restish binary and does not fetch from the network.

theme list shows the official theme names: catppuccin-latte, catppuccin-mocha, dracula, github-dark, gruvbox-dark, gruvbox-light, houston, minimal, monokai-pro-dark, monokai-pro-light, noctis, nord, one-dark-pro, restish-dark, restish-light, solarized-dark, synthwave-84, and vscode-dark.

Plugins

The plugins object stores plugin-specific config keyed by plugin name without the restish- prefix. Restish preserves each value as raw JSON and plugins can read it with the config-read plugin message. Users normally manage plugin installation separately with:

restish plugin list
restish plugin install rest-sh/restish csv
restish plugin remove restish-csv

Installed plugins are trusted local executables. Restish checks manifests and declared capabilities, but it does not sandbox plugin code.

Editing

Use config edit for larger changes:

restish config edit

Use api set for API-scoped patches:

restish api set example 'spec_url: https://api.rest.sh/openapi.json'
restish api set example \
  'profiles.demo.auth: {type: http-basic, params: {username: demo, password: env:EXAMPLE_PASSWORD}}'

Use config set for global patches:

restish config set \
  'apis.example.profiles.demo.auth: {type: http-basic, params: {username: demo, password: env:EXAMPLE_PASSWORD}}'
restish config set 'cache.max_size: 250MB'

config set and api set use shorthand patch expressions. Objects merge recursively, scalars replace, undefined deletes fields or array items, [] appends, [^index] inserts before an array index, and ^ moves or swaps values. Restish validates the final config before writing.

Precedence

Request behavior is layered from lower to higher precedence:

1. built-in defaults
2. API config
3. selected profile
4. environment variables
5. command-line flags

Explicit config selection is not layered. --rsh-config or RSH_CONFIG selects one config file for the invocation. Project-local config is explicit; Restish does not auto-discover config files from the current directory.

Related Pages

• Profiles
• Environment Variables
• API Management
• Shorthand
• Security Design