AdiPP/skills

Yaak CLI 技能

yaak 命令行工具（@yaakapp/cli）用于在终端中控制 Yaak 桌面 API 客户端。它直接读写与桌面应用相同的本地 SQLite 数据库——任何更改都会在两者之间即时同步。

前提条件

• 已安装 yaak CLI：npm install -g @yaakapp/cli
• Yaak 桌面应用（可选，但建议用于可视化验证）

全局标志

标志	用途
--data-dir <DIR>	自定义数据目录
-e, --environment <ID>	用于变量替换的环境 ID
--cookie-jar <ID>	用于请求执行的 Cookie Jar ID
-v, --verbose	详细输出（事件、流式响应体）
--log [LEVEL]	CLI 日志级别（error|warn|info|debug|trace）

命令树

yaak
├── workspace   list | show <id> | create | update <id> | delete <id> [--yes]
├── request     list [<ws-id>] | show <id> | create [<ws-id>] | update <id> | delete <id> [--yes] | send <id> | schema <type>
├── folder      list [<ws-id>] | show <id> | create -n <name> [<ws-id>] | update <id> | delete <id> [--yes]
├── environment list [<ws-id>] | show <id> | create | update <id> | delete <id> [--yes]
├── cookie-jar  list [<ws-id>]
├── send        <ID>                               # 请求、文件夹或工作空间
├── auth        login | logout | whoami
└── plugin      build | dev | generate | install | publish

多工作空间规则： 当只有一个工作空间时，[<ws-id>] 是可选的。如果有多个工作空间，则必须将工作空间 ID 作为第一个位置参数传递。

工作空间

yaak workspace list                                    # 列出所有工作空间
yaak workspace show <ws-id>                            # 完整 JSON
yaak workspace create -n "My API"                      # 通过名称创建
yaak workspace create --json '{"name":"My API","headers":[...]}'  # 带配置创建
yaak workspace update <ws-id> --json '{"name":"Renamed"}'
yaak workspace delete <ws-id> --yes                    # 非交互式删除

文件夹

yaak folder list [<ws-id>]                             # 列出工作空间中的文件夹
yaak folder show <folder-id>                           # 完整 JSON
yaak folder create -n "Auth" [<ws-id>]                 # 在工作空间中创建
yaak folder create --json '{"name":"Auth","workspaceId":"wk_..."}' [<ws-id>]
yaak folder update <folder-id> --json '{"name":"Renamed"}'
yaak folder delete <folder-id> --yes

请求

列表与查看

yaak request list [<ws-id>]                            # 列出所有请求
yaak request show <req-id>                             # 完整 JSON（方法、URL、头部、请求体等）

创建

快速标志：

yaak request create [<ws-id>] -n "Get Users" -m GET -u "https://api.example.com/users"

完整 JSON：

yaak request create [<ws-id>] --json '{
  "name": "Create User",
  "method": "POST",
  "url": "https://api.example.com/users",
  "folderId": "fl_...",
  "bodyType": "application/json",
  "body": {
    "text": "{\"name\":\"test\",\"email\":\"[email protected]\"}"
  },
  "headers": [
    {"name":"Authorization","value":"Bearer token","enabled":true}
  ]
}'

--json 的关键字段：

字段	类型	说明
name	字符串	显示名称
method	字符串	GET、POST、PUT、PATCH、DELETE
url	字符串	请求 URL
folderId	字符串	父文件夹 ID
bodyType	字符串	application/json、multipart/form-data、application/x-www-form-urlencoded、text/plain 等
body.text	字符串	请求体内容（对于 application/json，使用 JSON 字符串化）
headers	数组	[{name, value, enabled}]
authenticationType	字符串	basic、bearer、oauth2 等
authentication	对象	按类型的认证配置

更新

yaak request update <req-id> --json '{"name":"Updated Name","url":"https://new-url.com"}'

删除

yaak request delete <req-id> --yes

发送

yaak send <req-id>                                     # 发送单个请求
yaak send <req-id> -v                                  # 详细模式（头部、事件）
yaak send <folder-id>                                  # 发送文件夹中的所有请求
yaak send <ws-id> --parallel --fail-fast               # 发送整个工作空间

发送标志：

• --parallel — 并发执行请求
• --fail-fast — 首次失败时中止（适用于文件夹/工作空间发送）
• -e <env-id> — 使用环境进行变量替换
• -v — 详细输出（显示请求/响应头部、流式响应体）

Schema 内省

yaak request schema http       # HTTP 请求的 JSON Schema
yaak request schema grpc       # gRPC 请求的 JSON Schema
yaak request schema websocket  # WebSocket 请求的 JSON Schema

使用此命令了解创建/更新时 --json 负载的确切结构。

环境

yaak environment list [<ws-id>]                        # 列出环境
yaak environment show <env-id>                         # 包含变量的完整 JSON
yaak environment create [<ws-id>] -n "Production"
yaak environment update <env-id> --json '{
  "name": "Production",
  "variables": [
    {"name":"BASE_URL","value":"https://api.prod.com"},
    {"name":"API_KEY","value":"secret123"}
  ]
}'
yaak environment delete <env-id> --yes

使用环境

在任意 send 命令中传递 -e <env-id> 以进行变量替换：

yaak send <req-id> -e <env-id>

请求中的模板语法：

• 变量：${[ my_var ]}
• 函数：${[ uuid() ]}、${[ timestamp() ]}、${[ fs.readFile('/path') ]}

认证

yaak auth whoami                                       # 检查登录状态
yaak auth login                                        # 通过浏览器登录
yaak auth logout                                       # 退出登录

批量操作

从脚本创建多个请求

#!/bin/bash
WS="wk_..."
FL_AUTH="fl_..."
FL_PROD="fl_..."

# 认证端点
yaak request create "$WS" --json '{"name":"Login","method":"POST","url":"https://api.example.com/auth/login","folderId":"'