First run

Create a project

On first launch Tinspec asks for a project. You have two choices, and the difference matters:

• A project with a folder (recommended). Everything is written as plain YAML inside that folder, so you can commit it alongside the API it tests. This is the mode the rest of the docs assume.
• A folderless project. Nothing is written to disk. Useful for a scratch session; you lose run history, the spec cache, and any endpoint edits when the project closes.

Pick a folder — ideally one inside the repository of the service you are testing, so the tests travel with the code.

The last project you had open is remembered and reopened on the next launch.

The workspace

Three regions:

• The navigator on the left lists the project’s collections and their requests, your API providers and their endpoints (grouped by tag), and sections for Auth, Chains, Gateways, and Scripts. You choose which sections it shows, in Settings → General or by right-clicking the tab bar.
• The work area in the middle is a tab strip over the editor. Requests open here, and so do full-pane views — History, Settings, Environments, Auth providers, Spec Changes, Cookies, Mocks, Themes.
• The response dock at the bottom shows the last response for the active tab: status, timing, size, headers, body, and test results. It hides itself on tabs that can never have a response and comes back on tabs that can.

⌘B toggles the navigator, ⌘J the response dock. ⌘K opens the command palette, which is the fastest route to anything — including endpoint search. The full list is in Keyboard shortcuts.

The dock is tabbed, and a tab appears only when it has something to say: Timeline on a buffered HTTP response, Trailers on a gRPC call, Diff when there is a previous run or a spec example to compare against, Preview when the body is something that can be rendered. Read a response covers the whole dock.

Three ways to look at a request

Every request opens in one of three views, toggled at the top right and remembered per tab:

• Editor — a runnable .http buffer with spec-aware completion. ⌘↵ runs the block under the cursor.
• Docs — a reference rendering of the endpoint: typed parameters, body fields, response codes, a cURL snippet, and an inline Try it.
• Form — the classic builder, with Params / Headers / Body / Auth / Tests / Scripts / Settings tabs.

They are views of the same request, not different requests. Switch freely.

Settings

Settings opens as a tab like anything else, and it is sectioned — General, Endpoints, Sending, Network, Security, Guards, Editor & response, History, Cloud, AI, Updates — with a search box over all of them. Search matters here: the panel shows one section at a time, so without it a preference in a section you did not guess would be invisible. Every setting is in the index by construction, so a new preference cannot ship unfindable.

API provider settings and folder settings are tabbed the same way.

What ends up in git

Your project folder, after a little use:

my-api-tests/
├── users.yaml              ← a collection: requests, environments
├── orders.yaml
└── .tinspec/
    ├── chains/             ← one YAML per chain
    ├── auth/               ← auth provider definitions (no secret values)
    ├── providers/          ← API providers (spec bindings)
    ├── route-matchers/     ← gateway configs
    ├── overlays/           ← your edits to spec-generated endpoints
    ├── lib/                ← reusable JS snippets you insert into a hook
    ├── functions/          ← standalone JS you run for a one-off computation
    ├── themes/
    └── tinspec.db          ← run history + spec cache — do NOT commit

Commit everything except tinspec.db. See Project layout for what each file contains and a ready-made .gitignore line.

.tinspec/lib and .tinspec/functions hold plain .js files you can edit in your own editor. If you do, the Scripts view has a Write declarations button that generates .tinspec/tinspec.d.ts from the same list the app’s own completion uses, so your editor knows the ts.* library too. It is written when you ask for it, not on every save.

Note

Secret values are never written to any of these files. Auth definitions reference secrets by name; the values live in your OS keychain or a machine-local encrypted store. Committing this folder does not commit a credential.

Next

Bind your first API spec.