Variables & environments in .http files

Before environments, the format gives you file-level variables: declare @name = value at the top, reference it as {{name}} anywhere in the file:

@baseUrl = https://dev.api.example.com

### List orders
GET {{baseUrl}}/orders

### Create an order
POST {{baseUrl}}/orders
Content-Type: application/json

{ "sku": "KARVE-1" }

That solves repetition inside one file. The remaining problem: to point those requests at staging instead of dev, you have to edit the file — and that edit shows up in Git. (Variables themselves are covered in the format guide.)

An environment is a named set of variable values that lives outside the .http file. The file references {{baseUrl}} and {{token}}; the environment decides what those mean right now. Switch environment, and every request in every file follows — no edits, no diffs. The .http ecosystem has two conventions for storing them.

The VS Code REST Client, Visual Studio 2022, and the JetBrains HTTP Client read a JSON file named http-client.env.json placed next to the .http file (or in a parent directory). One JSON object per named environment; a special $shared environment supplies defaults:

{
  "$shared": { "apiVersion": "v2" },
  "dev":     { "baseUrl": "https://dev.api.example.com" },
  "prod":    { "baseUrl": "https://api.example.com" }
}

You pick the active environment from a dropdown in the editor, and {{baseUrl}} resolves accordingly. A companion http-client.env.json.user file (kept out of Git) holds per-developer secrets in the JetBrains flavor.

Karve keeps environments in the format ops tooling already uses: dotenv. One environment = one .env file on disk, plain KEY=value lines:

# .env.dev
baseUrl=https://dev.api.example.com
token=dev-token-here

# .env.prod
baseUrl=https://api.example.com
token=prod-token-here

How it works in the app:

1. Register your .env files in the Environments panel (or create new ones from a template there).
2. Click one to make it active — app-wide, shown in the status bar so you always know which server you're about to hit.
3. Send any request: the active file's values fill every {{variable}}. Edits to the .env apply on the next send — no reload.

Because an environment is just a file, it behaves like one: commit .env.dev for the team, git-ignore .env.prod with real credentials, copy one to a teammate, or edit it in Karve itself — .env files open in a plain-text tab.

When the same name is defined in both places, the file-level @var overrides the environment value. Think of the environment as the shared base and the file as the local override — handy for pinning one request to a specific host while everything else follows the active environment. Karve matches the VS Code REST Client here, so files keep behaving the same when they move between tools.

# active .env sets baseUrl=https://api.example.com
@baseUrl = http://localhost:5000   # ← this wins inside this file

GET {{baseUrl}}/health

The pattern that works:

• Reference secrets only as {{token}} in the committed .http file — never inline.
• Put real values in a .env that's listed in .gitignore.
• Commit a placeholder .env.example so teammates know which keys to fill in.

Auth headers specifically — bearer tokens, Basic auth, API keys — are covered in the authentication guide.