hitspec studio — a keyboard-first terminal API client

hitspec studio opens an interactive, keyboard-first workspace for your .http files without leaving the terminal. It is the fastest way to explore an API: edit a request, run it, inspect the tabbed response, and copy it out as curl or code — all from one screen.

hitspec studio                 # open the current directory
hitspec studio ./tests/        # open a directory
hitspec studio ./tests/users.http   # open a single file
hitspec studio --read-only     # browse and run, but refuse file and settings writes

ui is an alias for studio, so hitspec ui does the same thing. The older hitspec serve command still opens studio for backward compatibility, but hitspec studio is the dedicated command. Use hitspec serve --api-only when you want the REST/WebSocket API server instead of the UI.

What you get

Inline editing — a syntax-highlighted source pane you can edit and save (ctrl+s).
Run + tabbed response viewer — body, headers, assertions, timing, and captures.
Nine screens — workspace, stress, mock, contract, record, history, import, cookies, and settings.
Command palette (ctrl+p) — every action, searchable.
Copy/export — copy a request as curl, HTTPie, Python, JS fetch, Go, Ruby, or wget, including method, URL, headers, and body.
Environment + theme switchers — change the active environment (ctrl+e) or color theme (ctrl+t) live.
Workspace search (ctrl+f) and file watching — the file list and runs update as files change on disk.

Layout

The workspace screen is split into panes you cycle through with tab / shift+tab:

Pane	What it shows
Files	The `.http` / `.hitspec` files in the workspace
Requests	The named requests inside the selected file
Source	The raw, syntax-highlighted request source (editable)
Response	The tabbed response viewer after a run

A top bar shows the active environment and version; a bottom navigation strip and status line show the current screen, contextual key hints, and toasts. The layout adapts to the terminal. From 120 columns the source and response sit side by side; below that they share one panel, and studio switches that panel to the response when a run finishes (tab brings the source back). On a short terminal (under 30 rows) the headers and assertions row is dropped so the request list and the main panel keep their room. The headers and assertions panels follow the request highlighted in the list: what the file declares for it, or what it returned on its last run.

Screens

Press a number key (or use the palette) to switch screens:

Key	Screen	Purpose
`1`	Workspace	Browse, edit, and run requests
`2`	Stress	Run a load test and watch live metrics (progress follows the run’s own duration)
`3`	Mock	Start/stop a mock server from your files
`4`	Contract	Contract-test against an OpenAPI spec
`5`	Record	Start/stop a recording proxy and export captured traffic
`6`	History	Browse persistent run history with drill-down
`7`	Import	Import from curl, OpenAPI, Postman, or Insomnia
`8`	Cookies	Inspect the local cookie store (one global file shared by every workspace)
`9`	Settings	View/edit config and environments

Keyboard shortcuts

Press ? at any time for the in-app keyboard reference.

Screens

Key	Action
`1`-`9`	Jump to workspace, stress, mock, contract, record, history, import, cookies, settings

Workspace

Key	Action
`enter`	Open / select
`e`	Edit source (focus the inline editor)
`ctrl+s`	Save the edited file
`r`	Run the active request
`R`	Run every request in the file
`x`	Cancel the run in progress
`<` / `>` (or `,` / `.`)	In the response pane, show the previous / next request of a file run
`ctrl+r`	Refresh the workspace (rescan files + config)
`n`	New scratch file
`g`	Generate a sample project (`hitspec.yaml` + `example.http`)
`D`	Delete the selected file

r and R run what is in the editor, including edits you have not saved yet; the file on disk is not touched. A run takes the whole terminal’s attention: a second r while one is running is ignored, and x (or ctrl+c) cancels it — requests that had not started are skipped. After a file run, < and > step through every request’s response; the run opens on its first failing request.

Unsaved edits

Studio never drops your edits silently. Opening another file (enter in the file list, search), creating one, importing, renaming or duplicating, generating a sample, and quitting (q or ctrl+c) all ask first when the editor has unsaved changes. ctrl+s also checks the file on disk: if it was modified outside studio since you opened it, studio asks before overwriting it. If the open file is deleted outside studio while you have unsaved edits, studio keeps them, warns that the file was deleted on disk, and ctrl+s recreates the file from the editor.

Forms (stress, mock, contract, record, import, cookies, settings)

The screens that start something show a form with empty fields; the placeholder is the value used when a field is left blank. Nothing starts until you ask:

Key	Action
`e` or `enter`	Edit the fields
`tab` / `shift+tab` or `enter`	Next / previous field (while editing)
`ctrl+s`	Submit while editing the fields
`s`	Submit when not editing the fields
`x`	Stop (stress, mock, record)
`esc`	Leave the fields, then go back to the workspace

enter never submits a form, so a stray key cannot start a load test.

Stress profiles

The last field of the stress form is profile. Type the name of a stress profile saved in hitspec.yaml and start the test: the profile’s duration, rate, VUs and thresholds apply. With a profile named, a blank duration, rate, vus or max vus keeps the profile’s value, and a value you type wins over it. Without a profile, blank fields use the defaults shown (30s at 5 RPS). The idle stress screen lists the saved profile names; an unknown name shows an error and starts nothing.

Global

Key	Action
`ctrl+p`	Command palette
`ctrl+e`	Switch environment
`ctrl+t`	Switch theme
`ctrl+f`	Search requests (`enter` opens the file and selects the request)
`tab` / `shift+tab`	Next / previous pane
`esc`	Cancel / close an overlay
`?`	Help overlay
`q` / `ctrl+c`	Quit (`ctrl+c` cancels a run in progress first)

Command palette

Press ctrl+p to open the command palette — a searchable list of every action. Type / then a short, unique query to filter, then enter to run the highlighted command. The palette covers everything in the keymap plus actions that have no dedicated key, including:

Run the active request or whole file, save, edit, refresh.
File operations — new, rename, duplicate, delete, and generate a sample project.
Copy/export the selected request as curl, HTTPie, Python, JS fetch, or Go, and copy the last response body.
Quick request (ad-hoc) — run a one-off request by URL without saving a file.
Stress / mock / record — start and stop the load test, mock server, and recording proxy; export or clear recordings.
History / cookies / settings — open those screens, or clear run history.
Go to <screen> — jump to any of the nine screens by name.

Copy a request as code

Select a request and use the palette (ctrl+p) to copy it in the format you need:

Command	Output
Copy request as curl	A complete `curl` command
Copy request as HTTPie	An `http` (HTTPie) command
Copy request as Python	Python `requests` code
Copy request as fetch	A JavaScript `fetch()` snippet
Copy request as Go	Go `net/http` code
Copy response body	The last response body

Each snippet includes the request’s method, URL, headers, and body, so it is a runnable copy you can paste and tweak. It is the request highlighted in the list (named or not) as it is in the editor, and {{variables}} are filled in from the file and the active environment, the same values a run would use.

Every format includes query parameters and renders @auth bearer, basic, apiKey and apiKeyQuery as the matching header or query parameter; other @auth types get a comment asking you to add the credentials. The curl export is the most complete: the other formats skip requests with multipart or file bodies and show a SKIPPED comment in their place.

Ad-hoc requests

Use Quick request (ad-hoc) from the palette to fire a one-off request by URL and view the response without creating a file — handy for a quick probe while you work.

Environments

Press ctrl+e to open the environment switcher and pick the active environment. The default environment is the defaultEnvironment from hitspec.yaml, else dev; override it at launch with --env (and point at a specific config file with --config):

hitspec studio ./tests/ --env staging
hitspec studio ./tests/ --config ./ci/hitspec.yaml

Requests, stress runs, the mock server and contract verification all resolve {{variables}} such as {{baseUrl}} from the active environment. The top bar always shows which environment is active, and the Settings screen (9) lets you view and edit environment variables. See Environments for how environments are defined. The Settings screen also edits hitspec.yaml values such as timeout, proxy, headers, validateSSL and followRedirects. Studio uses them for every request it sends — single requests, file runs, ad-hoc requests, stress runs and contract checks — exactly as hitspec run does, and a change you save applies to the next run. The HITSPEC_TIMEOUT, HITSPEC_PROXY, HITSPEC_INSECURE, HITSPEC_PARALLEL, HITSPEC_CONCURRENCY and HITSPEC_BAIL environment variables take precedence over hitspec.yaml (the environment itself is chosen with --env). See the configuration reference for the full list.

Themes

Press ctrl+t to open the theme picker, or set a theme at launch with --theme:

hitspec studio --theme "Tokyo Night"

Built-in themes:

Nord
Catppuccin Mocha
Dracula
Tokyo Night
Gruvbox Dark

File watching

Studio watches the workspace by default (--watch, on by default) and refreshes the file list and live execution progress as files change on disk. Disable it with --watch=false if you prefer a static view.

Flags

Flag	Short	Description	Default
`--watch`	`-w`	Watch for file changes	`true`
`--read-only`		Refuse workspace and `hitspec.yaml` writes (running requests still works)	`false`
`--env`	`-e`	Default environment	`defaultEnvironment` from config, else `dev`
`--config`		Path to `hitspec.yaml`
`--verbose`	`-v`	Verbose logging	`false`
`--allow-shell`		Allow shell command execution	`false`
`--allow-db`		Allow database assertions	`false`
`--log-format`		Log format: `text` or `json`	`text`
`--log-level`		Log level: `debug`, `info`, `warn`, `error`	`info`
`--theme`		Color theme (see Themes)
`--mouse`		Capture the mouse for wheel scrolling	`false`

Studio does not capture the mouse by default, so your terminal can select and copy text as usual. Pass --mouse if you want the wheel to scroll the response pane; the terminal’s own selection then needs a modifier key (usually shift).

Shell commands and database assertions are disabled by default. Pass --allow-shell and/or --allow-db to enable them in studio, the same as with hitspec run.

Read-only mode

--read-only protects the workspace and hitspec.yaml: saving, creating, renaming and deleting files and editing settings or cookies are refused. Running requests, stress, mock, record and contract verification still work, and read-only runs do not save cookies. Use it to browse or demo a workspace without risking changes:

hitspec studio ./tests/ --read-only

Next steps

Quickstart

Write and run your first test, then open it in studio.

Editor Setup

Syntax highlighting and completions in VS Code, Neovim, and more.

Stress Testing

Drive a load test from the stress screen.

API Client Manager

How studio and serve share one in-process manager.

Getting Started

Core Concepts

Features

Guides

Examples

CLI Reference

Configuration

Assertions Reference

Built-in Functions

Authentication

Output Formats

Integrations

hitspec studio — a keyboard-first terminal API client

What you get

Layout

Screens

Keyboard shortcuts

Screens

Workspace

Unsaved edits

Forms (stress, mock, contract, record, import, cookies, settings)

Stress profiles

Global

Command palette

Copy a request as code

Ad-hoc requests

Environments

Themes

File watching

Flags

Read-only mode

Next steps

Quickstart

Editor Setup

Stress Testing

API Client Manager