Skip to main content

hitspec docs

Output AI-readable documentation (llms.txt) for AI agents to learn hitspec syntax.
This prints the complete hitspec specification in a format optimized for LLM consumption.

hitspec studio

Open the keyboard-first interactive app for working with hitspec files, right in the terminal.

What It Provides

  • Inline .http and .hitspec source editing with syntax highlighting and save
  • File tree, request table, response viewer, headers, assertions, and history
  • Stress, mock, contract, record, import, cookies, and settings screens
  • Copy/export as curl, HTTPie, Python, fetch, or Go; workspace search; environment switching
  • Command palette and keyboard-first navigation
  • Real-time file watching and execution progress

Flags

Themes

studio ships with five built-in color themes: Nord, Catppuccin Mocha, Dracula, Tokyo Night, and Gruvbox Dark. Switch at any time with ctrl+t (or the command palette), or set one at launch with --theme:

Examples

hitspec serve

Start the REST/WebSocket API server for scripts and integrations. With no flags it opens hitspec studio; pass --api-only to run just the API with no interactive UI.

What It Provides

  • REST endpoints under /api/v1/*
  • Realtime events over WebSocket at /api/v1/ws
  • The same parser, runner, history store, and engines as the CLI
No web SPA is served; non-API browser routes are not part of serve.

Flags

Security

The REST/WebSocket API can read/write and delete files, execute arbitrary requests (SSRF), and run shell commands when --allow-shell is set. By default it binds to localhost only, which limits exposure to your machine. If you bind to a network address (--host 0.0.0.0) or expose the port, set --api-token (or the HITSPEC_API_TOKEN env var) to require a shared secret. Clients must then send Authorization: Bearer <token> (REST) or ?token=<token> (WebSocket, which cannot set headers on the upgrade request). Requests with a missing or mismatched token get 401 Unauthorized. If the server is bound to a non-loopback address, or --allow-shell / --allow-db is set, and you did not configure a token, hitspec generates a random one and prints it once to stderr. Even on localhost the server defends against web pages that try to reach it through your browser: JSON bodies must be sent as application/json (415 otherwise), the Host header must be localhost, 127.0.0.1 or [::1] (403), and a request with an Origin header must come from a localhost origin on the server’s port, or on any port with --cors (403). See REST API. stateHandler in POST /contract/verify runs a program, so it needs --allow-shell and must point inside the workspace.

Examples

Last modified on October 19, 2026