mirror of
https://github.com/mountain-loop/yaak.git
synced 2026-08-25 21:04:04 +02:00
Gregory Schier
314f08545c
Teaches agents to drive the CLI: workspaces, environments, requests, sending, response chaining, and importing. SKILL.md stays lean with four references loaded on demand. The skill is embedded in the binary and written to ~/.agents/skills plus any detected tool directory, so it ships with the CLI and refreshes on update. Reinstalls keep files edited locally unless --force. Also fixes the `request schema http` hint for URL path parameters, which said to omit the leading colon. Names without the colon are sent as query string parameters instead, leaving the placeholder literal in the path.
123 lines
4.0 KiB
Markdown
123 lines
4.0 KiB
Markdown
# Environments and variables
|
|
|
|
## The hierarchy
|
|
|
|
Every workspace gets a base environment named **Global Variables** for free. Its
|
|
`parentModel` is `workspace`, and its variables apply to every send regardless of
|
|
which environment is selected.
|
|
|
|
Sub-environments (`parentModel: "environment"`) sit under the base and are chosen
|
|
per send with `-e`. A sub-environment variable overrides a base variable of the
|
|
same name; names it does not define fall through to the base.
|
|
|
|
```bash
|
|
yaak environment list wk_abc123
|
|
# ev_staging - Staging (environment)
|
|
# ev_production - Production (environment)
|
|
# ev_base - Global Variables (workspace)
|
|
```
|
|
|
|
The trailing parenthetical is `parentModel`, which is how you tell the base
|
|
environment from the rest.
|
|
|
|
## Setting variables
|
|
|
|
Variables are an array on the environment, so an update replaces the whole list.
|
|
Read first, then write the full array back:
|
|
|
|
```bash
|
|
yaak environment show ev_base
|
|
yaak environment update --json '{
|
|
"id": "ev_base",
|
|
"variables": [
|
|
{"name": "base_url", "value": "https://api.example.com", "enabled": true},
|
|
{"name": "api_version", "value": "v1", "enabled": true}
|
|
]
|
|
}'
|
|
```
|
|
|
|
Create a sub-environment with its variables in one step:
|
|
|
|
```bash
|
|
yaak environment create wk_abc123 --json '{
|
|
"name": "Staging",
|
|
"parentModel": "environment",
|
|
"variables": [{"name": "base_url", "value": "https://staging.example.com", "enabled": true}]
|
|
}'
|
|
```
|
|
|
|
`enabled: false` keeps a variable defined but inert, which is how the app models
|
|
a commented-out value.
|
|
|
|
## Using them
|
|
|
|
`${[ name ]}` resolves anywhere a value is rendered — URL, headers, body, and
|
|
authentication fields:
|
|
|
|
```bash
|
|
yaak request create wk_abc123 --json '{
|
|
"name": "List Pets",
|
|
"method": "GET",
|
|
"url": "${[ base_url ]}/${[ api_version ]}/pets",
|
|
"authenticationType": "bearer",
|
|
"authentication": {"token": "${[ api_token ]}"}
|
|
}'
|
|
```
|
|
|
|
Then run the same request against different targets:
|
|
|
|
```bash
|
|
yaak request send rq_abc123 # base environment only
|
|
yaak -e ev_staging request send rq_abc123 # staging overrides base_url
|
|
yaak -e ev_production send fl_smoke_tests # whole folder against production
|
|
```
|
|
|
|
`-e` is global, so it applies to `send`, `request send`, folder sends, and
|
|
workspace sends alike.
|
|
|
|
## Unresolved variables fail loudly
|
|
|
|
Referencing a name no active environment defines aborts before anything is sent:
|
|
|
|
```
|
|
Error: Failed to render request templates: Render Error: Variable "api_token" is not defined in active environment
|
|
```
|
|
|
|
Exit code 1. This is a feature worth relying on — a typo in a variable name can
|
|
never quietly send a request to `https:///pets`. When a send fails this way, the
|
|
fix is either the variable name in the request or the `-e` environment, not a
|
|
retry.
|
|
|
|
## Secrets
|
|
|
|
Do not write real credentials into environment variables on the user's behalf.
|
|
Create the reference and let the user supply the value:
|
|
|
|
```bash
|
|
yaak environment update --json '{"id":"ev_base","variables":[{"name":"api_token","value":"","enabled":true}]}'
|
|
```
|
|
|
|
Then tell the user which variable to fill in, and in which environment.
|
|
|
|
Environments have a `public` flag that mirrors the app's Sharable/Private toggle.
|
|
`public: false` (the default) marks the environment Private, which keeps it out
|
|
of `yaak export` unless `--include-private-environments` is passed. Secrets
|
|
belong in a private environment; values safe to commit or share belong in a
|
|
sharable one.
|
|
|
|
## Cookies
|
|
|
|
Cookie jars are per-workspace and require no setup — the oldest jar is used
|
|
automatically. Sending cookies is off by default per request; enable it with the
|
|
inherited setting, on the folder if it should apply to a whole group:
|
|
|
|
```json
|
|
"settingSendCookies": {"enabled": true, "value": true},
|
|
"settingStoreCookies": {"enabled": true, "value": true}
|
|
```
|
|
|
|
With both on, a login request stores its `Set-Cookie` and later requests in the
|
|
same jar send it back, which is often simpler than threading a token by hand.
|
|
Use `--cookie-jar cj_abc123` to select a non-default jar, and
|
|
`yaak cookie-jar list <wk_id>` to see the jars and their cookie counts.
|