Variables and environments

In .outry a variable is a bare name — customer: user_id — or ${name} inside a string and {name} in a path; in .http it is {{name}}. Values come from api/env.toml, from previous responses, from the command line, from environment variables and from the system keychain.

GET /users/{id} {
  query { version }
  headers { Authorization: "Bearer ${token}" }
}

Environments

default = "dev"           # used when --env is not given

[vars]                    # shared by all environments
version = "v1"

[env.dev]
base = "http://localhost:8080"

[env.prod]
base = "https://api.example.com"
version = "v2"            # overrides [vars]

outry run api              # dev
outry run api --env prod   # prod
outry envs                 # list environments, * marks the default

Full list of keys: env.toml reference.

Where a value comes from

When Outry resolves a variable, it takes the first match, top to bottom:

#	Source	Example
1	Command line overrides	`outry run api --var id=42`
2	Values saved by `save`	`save token = body.access_token`
3	Process environment variables `OUTRY_<NAME>`	`OUTRY_TOKEN=… outry run api`
4	The active environment `[env.<name>]`, then `[vars]`	`base = "http://localhost:8080"`
5	The system keychain	`outry secret set token`

The name of the environment variable is OUTRY_ plus the variable name in upper case, with any character other than letters and digits replaced by _: access-token → OUTRY_ACCESS_TOKEN.

If any variables are missing, the request is not sent and all missing names are listed at once:

✗ api/users/get.outry  GetUser
    undefined variable(s): base, id

In .outry, names declared in the request come first: call arguments, params and their defaults, then the file’s lets, then the table above. outry check --env prod lists variables that are not defined in an environment without sending anything.

Generated values

In .outry these are functions — uuid(), now(), nowIso(), randomInt(1, 100), randomString(8); see built-in functions.

Dynamic variables in .http

Names starting with $ are generated on every substitution, so each request (and each occurrence) gets a fresh value:

Variable	Value
`{{$uuid}}`	A random UUID v4
`{{$timestamp}}`	Current Unix time in seconds
`{{$randomInt}}`	A random integer from 0 to 999
`{{$randomInt 1 100}}`	A random integer from `min` (inclusive) to `max` (exclusive)

POST {{base}}/orders
Idempotency-Key: {{$uuid}}

{"amount": {{$randomInt 1 100}}, "created": {{$timestamp}}}

Inspecting variables

outry vars prints the final value of every variable and its source; secrets are masked:

outry vars --env prod

In the desktop app the Variables tab of the right panel shows the same list for the selected environment. See outry vars.

Saved values

Values captured with save (> save in .http) are available to the following requests in the same run and are remembered between runs, per project and environment. They are stored outside the repository, in ~/.local/share/outry/state/ (Linux), because they are often tokens.

Run with --fresh to ignore and not update saved values:

outry run api --fresh

To forget saved values for good, use Clear saved on the Variables tab in the app.

Responses of requests with cache: 30m are kept in the same file until they expire; --fresh and Clear saved skip and forget them too.

How the project is found

Outry looks for env.toml, or api/env.toml, starting from the file you run and going up through parent folders, stopping at the repository root (the folder with .git). The folder containing env.toml is the project root. Use --project <dir> to point at it explicitly.