> ## Documentation Index
> Fetch the complete documentation index at: https://hitspec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# hitspec docs, studio & serve

> Reference for the docs command, the interactive studio app, and the REST/WebSocket API server.

# hitspec docs

Output AI-readable documentation (`llms.txt`) for AI agents to learn hitspec syntax.

```bash theme={null}
hitspec docs
```

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.

```bash theme={null}
hitspec studio [file|directory] [flags]
```

## 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

| Flag            | Short | Description                                 | Default |
| --------------- | ----- | ------------------------------------------- | ------- |
| `--watch`       | `-w`  | Watch for file changes                      | `true`  |
| `--read-only`   |       | Disallow file mutations                     | `false` |
| `--env`         | `-e`  | Default environment                         | `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 below)                     | `Nord`  |

## 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`:

```bash theme={null}
hitspec studio --theme "Tokyo Night"
```

## Examples

```bash theme={null}
# Open the current directory
hitspec studio

# Open a specific workspace
hitspec studio ./tests/

# Open a single file
hitspec studio ./tests/users.http

# Inspect without file mutations
hitspec studio --read-only --env staging
```

***

# 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.

```bash theme={null}
hitspec serve [file|directory] [flags]
```

## 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

| Flag            | Short | Description                                                                       | Default     |
| --------------- | ----- | --------------------------------------------------------------------------------- | ----------- |
| `--api-only`    |       | REST/WebSocket API only, no interactive UI                                        | `false`     |
| `--port`        | `-p`  | API server port                                                                   | `4000`      |
| `--host`        |       | API bind address                                                                  | `localhost` |
| `--cors`        |       | Enable CORS headers                                                               | `false`     |
| `--watch`       | `-w`  | Watch for file changes                                                            | `true`      |
| `--read-only`   |       | Disallow mutating actions                                                         | `false`     |
| `--env`         | `-e`  | Default environment                                                               | `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-level`   |       | Log level: `debug`, `info`, `warn`, `error`                                       | `info`      |
| `--api-token`   |       | Require a bearer token for all REST/WebSocket requests (env: `HITSPEC_API_TOKEN`) |             |

## 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`.

## Examples

```bash theme={null}
# Start the REST/WebSocket API for integrations
hitspec serve --api-only --port 8080 --cors

# API server bound to localhost
hitspec serve --api-only --host localhost --port 4000

# Require a token before exposing the API on the network
HITSPEC_API_TOKEN=$SECRET hitspec serve --api-only --host 0.0.0.0 --port 4000
# clients: curl -H "Authorization: Bearer $SECRET" http://host:4000/api/v1/workspace
```