mirror of
https://github.com/mountain-loop/yaak.git
synced 2026-08-29 14:47:14 +02:00
Add a Yaak CLI skill for coding agents, installed by yaak agent install
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.
This commit is contained in:
Gregory Schier
@@ -0,0 +1,115 @@
|
||||
# Chaining requests
|
||||
|
||||
The usual way to feed one response into the next request is a shell pipeline:
|
||||
send, pipe through `jq`, stash in a variable, interpolate into the next command.
|
||||
Yaak does not need that. A request can reference another request's response
|
||||
directly, and Yaak resolves the dependency at send time — including sending the
|
||||
upstream request first if it has to.
|
||||
|
||||
This is the highest-leverage thing the CLI offers, because the chain is stored
|
||||
in the workspace. The user can re-run it from the app, and it keeps working
|
||||
after the shell session is gone.
|
||||
|
||||
## Reading a value out of another response
|
||||
|
||||
```
|
||||
${[ response.body.path(request='rq_login', path='$.token') ]}
|
||||
```
|
||||
|
||||
`request` is the upstream request's ID. `path` is JSONPath for JSON responses
|
||||
and XPath for XML. So a login-then-call-the-API pair is two requests and no glue:
|
||||
|
||||
```bash
|
||||
yaak request create wk_abc123 --json '{
|
||||
"name": "Login",
|
||||
"method": "POST",
|
||||
"url": "${[ base_url ]}/auth/login",
|
||||
"bodyType": "application/json",
|
||||
"body": {"text": "{\"user\":\"demo\",\"pass\":\"${[ password ]}\"}"},
|
||||
"headers": [{"name": "Content-Type", "value": "application/json", "enabled": true}]
|
||||
}'
|
||||
# -> Created request: rq_login
|
||||
|
||||
yaak request create wk_abc123 --json '{
|
||||
"name": "List Orders",
|
||||
"method": "GET",
|
||||
"url": "${[ base_url ]}/orders",
|
||||
"authenticationType": "bearer",
|
||||
"authentication": {"token": "${[ response.body.path(request='rq_login', path='$.token') ]}"}
|
||||
}'
|
||||
```
|
||||
|
||||
Sending "List Orders" now sends "Login" first when it needs to, extracts
|
||||
`$.token`, and puts it in the `Authorization` header.
|
||||
|
||||
Note the quoting: template function arguments use **single quotes**, so inside a
|
||||
single-quoted shell string write the payload to a file, or escape as above, or
|
||||
switch the outer shell quoting to double quotes and escape the inner JSON.
|
||||
Writing the JSON payload to a file and using `--json "$(cat payload.json)"` is
|
||||
the least error-prone for anything complex.
|
||||
|
||||
## Controlling when the upstream request re-sends
|
||||
|
||||
The `behavior` argument decides whether the dependency is actually sent:
|
||||
|
||||
| `behavior` | Meaning |
|
||||
|---|---|
|
||||
| `smart` (default) | Send only if there is no stored response yet |
|
||||
| `always` | Send every time |
|
||||
| `ttl` | Send if the newest response is older than `ttl` seconds (`0` never expires) |
|
||||
|
||||
```
|
||||
${[ response.body.path(request='rq_login', path='$.token', behavior='ttl', ttl='300') ]}
|
||||
```
|
||||
|
||||
`smart` is right for a token you fetch once. `ttl` matches a real token lifetime
|
||||
and is usually the best choice for auth. `always` is for values that must be
|
||||
fresh on every call, like a nonce.
|
||||
|
||||
## Other response accessors
|
||||
|
||||
```
|
||||
${[ response.header(request='rq_login', header='X-Request-Id') ]}
|
||||
${[ response.body.raw(request='rq_login') ]}
|
||||
```
|
||||
|
||||
`response.body.path` also accepts `behavior`/`ttl`, and has an alias of plain
|
||||
`response`.
|
||||
|
||||
## Other useful template functions
|
||||
|
||||
These come from bundled plugins and work anywhere a value is rendered:
|
||||
|
||||
| Function | Use |
|
||||
|---|---|
|
||||
| `uuid.v4()`, also `v1`, `v3`, `v5`, `v6`, `v7` | Idempotency keys, unique record names |
|
||||
| `timestamp.unix()`, `timestamp.unixMillis()`, `timestamp.iso8601()` | Timestamps in bodies or signatures |
|
||||
| `timestamp.format(...)`, `timestamp.offset(...)` | Formatted or relative times |
|
||||
| `random.range(min='1', max='100', decimals='0')` | Sample data |
|
||||
| `hash.sha256(input='…', encoding='hex')` | Digests — also `md5`, `sha1`, `sha512` |
|
||||
| `hmac.sha256(input='…', key='…', encoding='hex')` | Signed request signatures |
|
||||
| `base64.encode(input='…')`, `base64.decode(...)` | Encoded values |
|
||||
| `url.encode(input='…')`, `url.decode(...)` | Escaping values for URLs |
|
||||
| `fs.readFile(path='/abs/path', trim='true')` | Pull a value from a file on disk |
|
||||
| `cookie.value(name='session')` | Read a cookie from the jar |
|
||||
| `1password.item(...)` | Fetch a secret from 1Password rather than storing it |
|
||||
|
||||
Note the shapes that are easy to misremember: the encoders are `base64.encode`
|
||||
and `url.encode`, not `encode.base64`; the random function is `random.range`,
|
||||
not `random.number`; and there is no `timestamp.now`. Argument names vary per
|
||||
function, and a wrong name renders as an error rather than an empty string, so
|
||||
check the function in the app's template editor when unsure.
|
||||
|
||||
## When to chain and when not to
|
||||
|
||||
Chain when the dependency is part of the API's real shape: log in, then call;
|
||||
create a resource, then fetch it by the returned ID. The workspace becomes a
|
||||
runnable description of the API, which is the point.
|
||||
|
||||
Do not chain to smuggle in shell logic. If a value needs a conditional, a
|
||||
computation, or a retry, do that in the shell and set an environment variable.
|
||||
And do not build a long chain just to run a group of requests — `yaak send
|
||||
<fl_id>` already sends every request in a folder sequentially, with
|
||||
`--fail-fast` to stop at the first failure and `--parallel` when order does not
|
||||
matter. Reach for a chain when a request genuinely *depends* on another's
|
||||
response, not merely when it should run after it.
|
||||
@@ -0,0 +1,122 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,71 @@
|
||||
# Importing and exporting
|
||||
|
||||
## Import
|
||||
|
||||
```bash
|
||||
yaak import ./openapi.yaml
|
||||
```
|
||||
|
||||
One command, one positional file path. The format is auto-detected — OpenAPI 3,
|
||||
Swagger 2, Postman collections, Postman environments, Insomnia exports, cURL
|
||||
commands, and Yaak's own export format are all supported by bundled importer
|
||||
plugins. Output is a one-line summary:
|
||||
|
||||
```
|
||||
Imported 1 workspace, 1 environment, 1 folder, 3 HTTP requests
|
||||
```
|
||||
|
||||
By default this creates a **new workspace**. To merge into one that already
|
||||
exists:
|
||||
|
||||
```bash
|
||||
yaak import ./collection.json --workspace-id wk_abc123
|
||||
```
|
||||
|
||||
Not every importer honours `--workspace-id`; the flag applies where the importer
|
||||
supports it, and otherwise a new workspace is still created. Run
|
||||
`yaak workspace list` afterwards to see what you actually got.
|
||||
|
||||
**Reach for this first.** When the user has an OpenAPI spec, a Postman
|
||||
collection, or even a directory of `curl` commands in a README, importing beats
|
||||
authoring requests by hand — it is one command, it preserves names and grouping,
|
||||
and it will not typo a URL. Author requests by hand when there is no spec, or
|
||||
when the user wants a small hand-picked set rather than every endpoint.
|
||||
|
||||
A cURL import is a fast way to turn something the user already has into a saved
|
||||
request:
|
||||
|
||||
```bash
|
||||
echo "curl -X POST https://api.example.com/pets -H 'Content-Type: application/json' -d '{\"name\":\"Rex\"}'" > /tmp/req.txt
|
||||
yaak import /tmp/req.txt
|
||||
```
|
||||
|
||||
## After importing
|
||||
|
||||
An imported spec gives you requests pointing at whatever `servers` the spec
|
||||
declared. The usual follow-up is to make the host swappable:
|
||||
|
||||
1. `yaak request list <wk_id>` to see what landed.
|
||||
2. Put the host in a base environment variable (`base_url`).
|
||||
3. Update the imported requests to use `${[ base_url ]}`, then add a
|
||||
sub-environment per deployment target.
|
||||
|
||||
See [environments.md](environments.md). At that point `yaak -e ev_staging send
|
||||
<wk_id>` runs the whole imported API against staging.
|
||||
|
||||
## Export
|
||||
|
||||
```bash
|
||||
yaak export ./backup.json # the only workspace, when there is one
|
||||
yaak export ./backup.json wk_abc123 # a specific workspace
|
||||
yaak export ./backup.json wk_abc wk_def # several
|
||||
yaak export ./backup.json --all # everything
|
||||
```
|
||||
|
||||
Private environments are **excluded** unless you pass
|
||||
`--include-private-environments`. That default exists so an export can be
|
||||
committed to a repository without leaking credentials — do not add the flag
|
||||
just to make an export look complete. Add it only when the user explicitly wants
|
||||
a full backup, and say so when you do.
|
||||
|
||||
The output is Yaak's own format, so `yaak import ./backup.json` round-trips it.
|
||||
@@ -0,0 +1,195 @@
|
||||
# Authoring requests
|
||||
|
||||
Everything here is a field on the HTTP request model. Run
|
||||
`yaak request schema http --pretty` to see the full, current schema, including
|
||||
the authentication variants contributed by installed plugins.
|
||||
|
||||
## Two ways to create
|
||||
|
||||
Name, method, and URL have flags. Everything else needs JSON:
|
||||
|
||||
```bash
|
||||
yaak request create wk_abc123 --name "List Pets" --method GET --url "https://api.example.com/pets"
|
||||
```
|
||||
|
||||
```bash
|
||||
yaak request create wk_abc123 --json '{
|
||||
"name": "Create Pet",
|
||||
"method": "POST",
|
||||
"url": "https://api.example.com/pets",
|
||||
"bodyType": "application/json",
|
||||
"body": {"text": "{\"name\":\"Rex\",\"species\":\"dog\"}"},
|
||||
"headers": [{"name": "Content-Type", "value": "application/json", "enabled": true}]
|
||||
}'
|
||||
```
|
||||
|
||||
Flags and JSON cannot be mixed on the same command. The workspace ID may be
|
||||
omitted when only one workspace exists, and may also be carried inside the
|
||||
payload as `workspaceId`.
|
||||
|
||||
## Bodies
|
||||
|
||||
`bodyType` decides how `body` is encoded onto the wire, and `body` is a
|
||||
free-form object whose shape depends on that type. For text-ish types the
|
||||
content lives in `body.text` as a **string**, so a JSON payload is
|
||||
double-encoded: a JSON string containing JSON.
|
||||
|
||||
| `bodyType` | `body` |
|
||||
|---|---|
|
||||
| `application/json` | `{"text": "{\"key\":\"value\"}"}` |
|
||||
| `text/xml` | `{"text": "<root/>"}` |
|
||||
| `other` | `{"text": "…"}` |
|
||||
| `graphql` | `{"query": "{ pets { id } }", "variables": "{\"n\":1}", "operationName": ""}` |
|
||||
| `application/x-www-form-urlencoded` | `{"form": [{"name":"a","value":"1","enabled":true}]}` |
|
||||
| `multipart/form-data` | `{"form": [{"name":"file","file":"/abs/path","enabled":true}]}` |
|
||||
| `binary` | `{"filePath": "/abs/path"}` |
|
||||
| `null` (omitted) | no body |
|
||||
|
||||
For `graphql`, note that `variables` is a **string** of JSON, not an object, and
|
||||
that a GraphQL request sent with method `GET` moves query/variables/operationName
|
||||
into the query string and sends no body at all.
|
||||
|
||||
For `multipart/form-data`, each entry is either a text field (`value`) or a file
|
||||
(`file`, an absolute path), and may carry its own `contentType`.
|
||||
|
||||
**Add the `Content-Type` header yourself.** In the desktop app, choosing a body
|
||||
type also writes a matching `Content-Type` into the request's headers, so it is
|
||||
stored on the request rather than inferred at send time. Creating a request from
|
||||
the CLI skips that step: `bodyType` alone controls how the body is *encoded*, and
|
||||
nothing adds the header. A JSON body with no `Content-Type` goes out as untyped
|
||||
bytes, which many APIs answer with 400 or 415.
|
||||
|
||||
```json
|
||||
"bodyType": "application/json",
|
||||
"body": {"text": "{\"name\":\"Rex\"}"},
|
||||
"headers": [{"name": "Content-Type", "value": "application/json", "enabled": true}]
|
||||
```
|
||||
|
||||
Use the same value as `bodyType`, with two exceptions the app also makes: `other`
|
||||
pairs with `text/plain`, and `graphql` pairs with `application/json`. Multipart is
|
||||
the one case to leave alone — the sender replaces that header with one carrying
|
||||
the generated boundary.
|
||||
|
||||
Requests created this way end up identical to app-created ones, which matters
|
||||
because the user will open them in the app afterwards.
|
||||
|
||||
## Headers
|
||||
|
||||
```json
|
||||
"headers": [
|
||||
{"name": "Accept", "value": "application/json", "enabled": true},
|
||||
{"name": "X-Debug", "value": "1", "enabled": false}
|
||||
]
|
||||
```
|
||||
|
||||
`enabled: false` keeps a header in the app for the user to toggle without
|
||||
sending it. Values accept template variables.
|
||||
|
||||
## URL parameters
|
||||
|
||||
One array covers both query string entries and path placeholders. A parameter
|
||||
fills a path placeholder only when its **name starts with a colon** and matches
|
||||
the placeholder in the URL. Everything else becomes a query string entry:
|
||||
|
||||
```json
|
||||
"url": "https://api.example.com/pets/:petId/visits",
|
||||
"urlParameters": [
|
||||
{"name": ":petId", "value": "42", "enabled": true},
|
||||
{"name": "limit", "value": "10", "enabled": true}
|
||||
]
|
||||
```
|
||||
|
||||
That sends `https://api.example.com/pets/42/visits?limit=10` — `:petId` is
|
||||
substituted into the path and dropped from the query string, `limit` is not.
|
||||
|
||||
This is the single easiest thing to get wrong here, and it fails **silently**.
|
||||
Naming the parameter `petId` instead of `:petId` leaves `/pets/:petId/visits` in
|
||||
the path as literal text and appends `?petId=42`, which most servers answer with
|
||||
a 404. Always include the colon, and confirm with `yaak -v request send <id>`
|
||||
that the `> GET …` line shows a substituted path.
|
||||
|
||||
## Authentication
|
||||
|
||||
`authenticationType` names a strategy and `authentication` holds its values. The
|
||||
strategy names are not always what you would guess — the built-ins are `basic`,
|
||||
`bearer`, `apikey`, `jwt`, `oauth1`, `oauth2`, `awsv4` (not "aws"), and
|
||||
`windows` (not "ntlm"). Installed plugins can add more.
|
||||
|
||||
```json
|
||||
"authenticationType": "bearer",
|
||||
"authentication": {"token": "${[ api_token ]}"}
|
||||
```
|
||||
|
||||
```json
|
||||
"authenticationType": "basic",
|
||||
"authentication": {"username": "admin", "password": "${[ admin_password ]}"}
|
||||
```
|
||||
|
||||
```json
|
||||
"authenticationType": "apikey",
|
||||
"authentication": {"location": "header", "key": "X-Api-Key", "value": "${[ api_key ]}"}
|
||||
```
|
||||
|
||||
The exact fields for each strategy, and which are required, are in the
|
||||
`authentication` property of `yaak request schema http --pretty`, which
|
||||
enumerates every installed strategy as a named variant. Read it rather than
|
||||
guessing — `oauth2` has fifteen fields and `jwt` requires four.
|
||||
|
||||
Set `authenticationType` to `null` to send no auth and stop inheriting from the
|
||||
parent folder.
|
||||
|
||||
## Folders and inheritance
|
||||
|
||||
Folders are containers *and* a place to put shared configuration. Headers and
|
||||
authentication set on a folder apply to every request inside it, so the common
|
||||
pattern is one folder per API surface holding the auth:
|
||||
|
||||
```bash
|
||||
yaak folder create wk_abc123 --name "Admin API"
|
||||
yaak folder update --json '{
|
||||
"id": "fl_abc123",
|
||||
"authenticationType": "bearer",
|
||||
"authentication": {"token": "${[ admin_token ]}"},
|
||||
"headers": [{"name": "X-Api-Version", "value": "2024-01-01", "enabled": true}]
|
||||
}'
|
||||
yaak request create wk_abc123 --json '{"name":"List Users","method":"GET","url":"${[ base_url ]}/users","folderId":"fl_abc123"}'
|
||||
```
|
||||
|
||||
The request above sends both the folder's bearer token and its version header
|
||||
without repeating either. A request that sets its own `authenticationType`
|
||||
overrides the folder's.
|
||||
|
||||
Nest folders by setting a folder's `folderId`. `yaak send <fl_id>` sends every
|
||||
request in the folder recursively.
|
||||
|
||||
## Per-request settings
|
||||
|
||||
Each `setting*` field is an inherited toggle shaped
|
||||
`{"enabled": bool, "value": …}`, where `enabled` means "override the inherited
|
||||
value" rather than "turn the feature on":
|
||||
|
||||
```json
|
||||
"settingFollowRedirects": {"enabled": true, "value": false},
|
||||
"settingRequestTimeout": {"enabled": true, "value": 5000}
|
||||
```
|
||||
|
||||
Available: `settingFollowRedirects`, `settingRequestTimeout` (ms, `0` for none),
|
||||
`settingValidateCertificates`, `settingSendCookies`, `settingStoreCookies`.
|
||||
|
||||
## Updating
|
||||
|
||||
Updates are JSON merge patches keyed by `id`. Send only what changes:
|
||||
|
||||
```bash
|
||||
yaak request update --json '{"id":"rq_abc123","method":"PATCH"}'
|
||||
```
|
||||
|
||||
Arrays are replaced wholesale, not merged — to add one header, read the current
|
||||
list with `yaak request show rq_abc123` and write the full new array back.
|
||||
Setting a key to `null` removes it.
|
||||
|
||||
## Ordering
|
||||
|
||||
`sortPriority` (a float) controls display order in the app sidebar. Leave it at
|
||||
`0` unless the user cares; requests created with the same priority fall back to
|
||||
creation order.
|
||||
Reference in New Issue
Block a user