mirror of
https://github.com/mountain-loop/yaak.git
synced 2026-08-26 21:34:07 +02:00
Gregory Schier
f53887a114
Stored responses were unreachable from the CLI even though the model layer has had list/get/delete all along. After a send, an agent could only see the body it just streamed: no status, no timing, no history. `yaak response list|show|body|delete` closes that. `show` and `body` accept a request ID as shorthand for its most recent response, which is the common case, and `show` returns status, reason, timing, headers, the final URL, and any transport error as JSON. `request create` also accepted payloads for request types it cannot create. A gRPC-shaped payload deserialized into an HttpRequest with the unknown fields dropped, so the gRPC method name landed in `method`, `service` vanished, and the result looked like a successful create. It now rejects a non-`http_request` `model`, and any field that is not part of the HTTP request schema, pointing at the app instead. `request update` had the same silent-drop behavior and gets the same check. The skill now points at `response show` rather than teaching agents to grep verbose send output for the status line.
144 lines
6.8 KiB
Markdown
144 lines
6.8 KiB
Markdown
---
|
|
name: use-yaak
|
|
description: >
|
|
Build and run HTTP API requests with the Yaak CLI (`yaak`): create workspaces,
|
|
folders, environments and variables, author HTTP requests, configure
|
|
authentication (OAuth 2.0, bearer tokens, API keys, basic, JWT, AWS SigV4),
|
|
send them individually or a whole folder/workspace at once, chain one
|
|
request's response into the next, and import existing APIs from OpenAPI,
|
|
Postman, Insomnia, or cURL. Use this skill whenever the user mentions Yaak, a
|
|
Yaak workspace, or the `yaak` command, and also when they ask to try, hit,
|
|
call, exercise, or smoke test an HTTP or REST endpoint, to save or organize
|
|
API requests for reuse, to set up API requests for manual testing, to add auth
|
|
to a saved request, to turn an OpenAPI or Postman collection into runnable
|
|
requests, or to run a saved request suite against staging versus production.
|
|
Prefer this over one-off `curl` commands whenever the requests should be
|
|
saved, reused, shared, or run as a set.
|
|
allowed-tools: Bash(yaak:*), Bash(which:*), Bash(command:*), Bash(npm:*), Bash(npx:*)
|
|
---
|
|
|
|
# Use Yaak
|
|
|
|
Yaak is a desktop API client. The `yaak` CLI reads and writes the **same local
|
|
database as the desktop app**, so anything you create shows up in the app
|
|
immediately, and vice versa. There is no server and no sign-in: `yaak auth` is
|
|
only for publishing plugins to the Yaak registry.
|
|
|
|
Two consequences worth holding onto. Requests you create are permanent user data
|
|
in an app they use, not scratch files, so name them the way the user would and
|
|
clean up anything created just to test. And because the app is right there, the
|
|
CLI is usually the wrong place to *read* a response in detail; it is the right
|
|
place to build, organize, and run requests.
|
|
|
|
## The CLI describes itself
|
|
|
|
**This skill deliberately does not list fields, body types, auth strategies, or
|
|
template functions.** The user's CLI version and installed plugins decide what
|
|
exists, so any list written here would eventually be wrong. Ask the CLI:
|
|
|
|
```bash
|
|
yaak --help # commands, plus agent hints at the bottom
|
|
yaak <command> --help # flags for one command
|
|
yaak request schema http --pretty # full request model, with guidance per field
|
|
yaak template-function list [filter] # template functions from installed plugins
|
|
yaak template-function show <name> # one function's arguments
|
|
```
|
|
|
|
`request schema http` is generated from the real model and merges in the auth
|
|
strategies contributed by plugins, so it is the authoritative answer for what a
|
|
request payload may contain and what each auth strategy needs. `workspace`,
|
|
`environment`, and `folder` have `schema` subcommands too.
|
|
|
|
Read the relevant schema before writing a JSON payload you are not certain of.
|
|
That is faster than a failed send, and it stays correct as Yaak changes.
|
|
|
|
## Resource model
|
|
|
|
- **Workspace** (`wk_…`) is the top-level container.
|
|
- **Folder** (`fl_…`) groups requests and can nest. Folders carry headers and
|
|
authentication that child requests inherit, which is the usual way to apply
|
|
one token to a whole group.
|
|
- **Request** (`rq_…`) is a single HTTP, gRPC, or WebSocket request. The CLI can
|
|
currently only create and send HTTP ones.
|
|
- **Environment** (`ev_…`) holds variables. Each workspace has a base
|
|
environment plus any number of sub-environments; a sub-environment overrides
|
|
base variables of the same name and is chosen per send with `-e`.
|
|
- **Cookie jar** (`cj_…`) stores cookies per workspace. The oldest is used by
|
|
default, so this normally needs no attention.
|
|
|
|
IDs are prefix-typed, so you can always tell what an ID refers to. Commands that
|
|
take a workspace ID infer it when exactly one workspace exists.
|
|
|
|
## Getting oriented
|
|
|
|
```bash
|
|
yaak --version || npm install -g @yaakapp/cli
|
|
yaak workspace list
|
|
```
|
|
|
|
Pick the workspace matching the user's project before changing anything, and
|
|
create one only when nothing fits. If a documented command is unrecognized, the
|
|
CLI is older than this skill: update it with `npm install -g @yaakapp/cli@latest`
|
|
and re-run `yaak agent install`, then tell the user to restart their coding tool.
|
|
**When the CLI and this skill disagree, the CLI is right.**
|
|
|
|
## Core workflows
|
|
|
|
**Start from a spec when one exists.** `yaak import <file>` auto-detects OpenAPI,
|
|
Swagger, Postman, Insomnia, cURL, and Yaak exports, and beats authoring requests
|
|
by hand every time.
|
|
|
|
**Make the host swappable.** Put the base URL in a base-environment variable,
|
|
reference it as `${[ base_url ]}`, then add a sub-environment per deployment
|
|
target. Now `yaak -e ev_staging send <wk_id>` runs everything against staging.
|
|
|
|
**Chain instead of shell-plumbing.** A request can read another request's
|
|
response directly, and Yaak sends the dependency first if it needs to:
|
|
|
|
```
|
|
${[ response.body.path(request='rq_login', path='$.token') ]}
|
|
```
|
|
|
|
Run `yaak template-function show response.body.path` for its arguments,
|
|
including how to control when the upstream request re-sends. Chain when a
|
|
request genuinely depends on another's response; to merely run requests in
|
|
order, `yaak send <fl_id>` already does that.
|
|
|
|
**Run a set.** `yaak send` accepts a folder or workspace ID, with `--fail-fast`
|
|
and `--parallel`. Workspace and request IDs survive an export/import, so a
|
|
committed `yaak export` plus `--data-dir ./.yaak` gives a runnable suite in CI.
|
|
|
|
## Reading results
|
|
|
|
A plain send writes only the response body to stdout. Yaak also stores every
|
|
response, so the reliable way to see what happened is to ask afterwards rather
|
|
than to parse the send output:
|
|
|
|
```bash
|
|
yaak response show rq_abc123 # latest response for a request, as JSON
|
|
yaak response list rq_abc123 # its history, newest first
|
|
yaak response body rq_abc123 # just the body
|
|
```
|
|
|
|
`response show` gives status, reason, timing, headers, the final URL, and any
|
|
transport error. Pass a response ID for a specific one. `-v` on a send prints
|
|
the same information live, prefixed `*`, `>`, and `<`, but interleaves it with
|
|
the body on stdout, so prefer `response show` when you need to act on the result.
|
|
|
|
Exit code 1 means the send did not complete: an unresolved template variable, an
|
|
unreachable host, a TLS failure. **HTTP error statuses are not failures.** Like
|
|
`curl`, a 404 or 500 exits 0, and a folder of requests that all return 500
|
|
reports success. Never tell the user an API is healthy based on a clean exit;
|
|
check the status.
|
|
|
|
## Execution rules
|
|
|
|
1. Resolve the workspace before mutating, and prefer an existing one.
|
|
2. Read the schema rather than guessing field names, auth fields, or body shapes.
|
|
3. `update` takes a JSON merge patch keyed by `id`: send only what changes, and
|
|
note that arrays are replaced wholesale, not merged.
|
|
4. Deletes need `--yes` in a non-interactive shell. Confirm with the user first.
|
|
5. Never write a real secret into an environment variable on the user's behalf.
|
|
Reference one and let them fill in the value.
|
|
6. Verify what you built by sending it, and report the real HTTP status.
|