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, and Gateways.
• 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, Cookies, 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.

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

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

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
    ├── 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.

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.