使用 tb CLI

tb 是 tool-bridge 的完整命令行客户端。它覆盖常用数据面与管理面，并把错误、分页和 JSON 输出做成适合脚本的形式；它不是唯一入口，所有请求最终仍服从同一 HTTP 契约和权限模型。

什么时候使用 CLI

适合交互式探索、部署验收、CI 脚本、SecretStore 管理、Device 长连接和无需浏览器的服务器环境。

如果只需要把能力嵌入程序，直接 HTTP 或 SDK 通常更简单；如果需要可视化浏览和表单校验，可使用 Dashboard。

安装与目标配置

npm install -g @tool-bridge/cli
tb --version

当前 npm 包要求 Node.js 22+。也可以使用官方 CLI 容器，或从源码为目标平台构建 Bun 独立二进制；生产环境固定明确版本或 digest，不把浮动 tag 当稳定发布。

交互登录会提示输入 SK，避免把明文写进 shell history：

tb login --base-url https://tb.example.com --profile team-a
tb whoami

# 以后需要从其他 profile 切回来时
tb use team-a
tb whoami

配置通常保存到用户配置目录。自动化环境不必先 login，可以注入：

export TB_BASE_URL=https://tb.example.com
export TB_SK="$(< /run/secrets/tool-bridge-sk)"
tb status --json

不要把 SK 烘焙进镜像、CI YAML 或共享脚本。容器使用 Docker/Kubernetes Secret，CI 使用受保护的 secret store。

CLI 的解析与输出约定

全局参数 --json、--base-url、--sk、--timeout 可以出现在 root、group 或 leaf 层级。未知 flag、多余 positional 和缺少必填参数都会失败，不会静默忽略拼写错误。

tb --json tree --depth 2
tb tree --depth 2 --json

两种写法语义相同。脚本应使用 --json，检查非零退出码，并把 stderr 与 stdout 分开。列表与搜索命令使用 --limit 和不透明 --cursor；cursor 只是继续位置，不是权限凭据。

--timeout 表示单个 HTTP 请求上限，不适用于 connect 等长驻命令，CLI 会明确拒绝。

所有失败路径都会归一成结构化错误，而不是只打印一段人类文案。--json 模式下，错误以单行 JSON 写入 stdout，退出码为 1；人类模式则把 error: <message> 写 stderr，retryable 时追加提示。

{ "ok": false, "error": "…", "code": "unavailable", "retryable": true }

脚本解析 stdout 的 ok/code 分支，只在 retryable 为真且操作可安全重试时退避重试；不要解析人类文案。code 的 7 码契约（invalid_argument、permission_denied、not_found、conflict、rate_limited、unavailable、internal）覆盖服务端与传输层失败；命令行参数解析错误不在其内，code 形如 commander.unknownOption 且没有 retryable，判 retryable 前先确认 code 不是 commander.*。

tb call 遇到 unavailable、internal、invalid_argument 或 rate_limited 时，会尽力查询该完整命令路径的 Feedback。JSON 错误可能额外带 hint 与最多三条精简 feedback；人类输出会给出对应的 tb feedback get 提示。自动查询失败不会覆盖原始错误。先读这些已知经验，再决定是否安全重试；没有条目时，CLI 只生成 submit 提示，不会替你自动提交。

推荐工作流：先发现，再调用

这套顺序与直接 HTTP 客户端一致；完整原则见从 ~help 到调用。

tb whoami
tb status
tb ls
tb tree --depth 2
tb search "document search"
tb search "document search" --schemas
tb help tools/docs
tb help tools/docs/search --json

tb search 只有宿主启用全局 Search 时可用。没有 Search 时从 tb tree 和父路径 tb help 继续，不要把 404 当成部署整体故障。

tb search 默认请求 compact 结果，--json 也一样。--schemas 会在同一次搜索请求中改用 detail: full，使结果带完整 schema；也适用于 --json。Search 目前只支持 keyword 模式，支持 --matching best|all、--min-coverage、--path-prefix、可重复 --effect 与 --federation local|recursive。结果中的 coverage、effect、source 与 partial 需要一起判断，partial 不是完整搜索成功。

调用只有一种形态：把 ~help 返回的 cmds[].path 原样交给 tb call。这个路径已经包含命令叶子，arguments 直接作为请求 body，不再向节点发送 {tool, arguments} 信封。

# 第二个 positional 是 arguments JSON
tb call tools/docs/search '{"query":"tool-bridge"}'

# builtin、Context、Device 等 kind 使用同一个直连形态
tb call system/status/get
tb call tools/docs/search --args '{"query":"tool-bridge"}'

arguments 有四个来源，彼此互斥（给两个即报错，不是优先级）：positional JSON、--args <json>、--args-file <file>（传 - 从 stdin 读取，stdin 是 TTY 时拒绝），以及可重复的扁平参数 --arg key=value。任何 JSON 源都必须是一个 JSON object，数组、标量或 null 会被拒绝。

# 从 stdin 读取 arguments，适合复杂或敏感输入
cat args.json | tb call tools/docs/search --args-file -

# 扁平参数：只做保守标量推断
tb call tools/docs/search --arg query=tool-bridge --arg limit=5

--arg 只做保守标量推断：true/false 转布尔、null 转 null、纯数字转 number，其余一律按字符串处理；重复 key 后者覆盖。它不解析嵌套对象、数组或 key:=json 语法——需要精确类型（字符串 "true"、字符串 "42"、大整数）或嵌套结构时改用 --args / --args-file。完整互斥与推断规则以 tb call --help 为准。复杂或敏感输入优先用 stdin 或 --args-file，避免 shell quoting 和 history 泄露。

Device 命令的实时与离线投递

设备命令的 ~help 可能带 delivery: realtime|mailbox|both。这是命令能力；调用方再用 tb call --delivery 选择本次策略：

# 只走当前 WebSocket；也是不传 --delivery 时的缺省行为
tb call device/build-01/ops/sync --arg repository=acme/app --delivery realtime

# 直接创建 durable operation
tb call device/build-01/ops/sync \
  --arg repository=acme/app \
  --delivery mailbox \
  --ttl 900 \
  --idempotency-key sync-acme-app-20260901

# 在线时实时执行；只有网关能确定尚未派发时才入队
tb call device/build-01/ops/sync \
  --arg repository=acme/app \
  --delivery fallback \
  --ttl 900 \
  --idempotency-key sync-acme-app-20260901

--ttl 必须是正整数秒；它和 --idempotency-key 只允许与 mailbox/fallback 同用。CLI 只发送一次普通 command POST，不会在实时错误后自行发送第二次 enqueue 请求。实际入队返回 202，人类模式打印 operation id；脚本用 --json 保存完整 operation。

查询与取消使用独立管理面：

tb device op ls build-01
tb device op ls build-01 --state queued --state claimed
tb device op get build-01 <operation-id>
tb device op cancel build-01 <operation-id>

result_unknown 是“已经开始、结果未知”；expired 且 executionMayHaveOccurred:true 是“可能执行过”。两者都不能按“安全未执行”自动重试。完整状态与设备侧接线见Device 离线投递与 Mailbox。

常用任务地图

任务	命令族	动态真源
浏览树和契约	`tb ls/tree/help/search`	目标路径 `~help`、可选 `~search`
调用工具	`tb call`	工具级 `tb help <path>/<tool> --json`；或 `tb help <path> --schemas` 一次取回整节点 schema
管理 SK/凭证	`tb sk`、`tb secret`	`tb help system/sk`、`system/secret`
挂载工具	`tb integration`、`tb tool`	`system/catalog`、节点 `~help`
使用 Context	`tb ctx`	namespace `~help` 的实际 methods
设备连接与投递	`tb connect`、`tb device`、`tb call --delivery`、`tb mount fs`	`tb connect --help`、设备路径 `~help`、Device Mailbox
联邦	`tb federation`、`tb server`	`system/federation`、remote 节点 `~help`
协作经验	`tb feedback`、`tb note`	路径 `~feedback` 与 `~help`
外部 Plugin	`tb plugin`	`system/plugin` 与 Plugin `~describe`

上传对象与管理实例

tb store upload ./report.pdf --json
tb store ls
tb config get
tb config status
tb storage list
tb deployment status
tb maintenance status
tb keys status

Store 是独立对象能力，与 tb ctx 的命名内容分开。运行设置通过 tb config 显式保存再 apply；连接、后端和 keyring 通过对应管理命令处理。密钥及连接输入使用文件/stdin。

首次安装还可使用 tb setup status|defaults|configure；本机 tb setup pair --directory <path> 调用同机 admin utility，不要求已有 Admin SK。完整步骤见快速上手。

Secret 和 SK 的安全用法

SecretStore 值优先从 stdin 写入：

tb secret set --name upstream-api < api.key
tb secret ls

tb secret ls 只返回名称和更新时间。CLI 没有读取 secret 明文的命令。

签发 SK 时从最小路径和动作开始，并立即保存一次性明文：

tb sk create \
  --owner agent:docs \
  --scope 'tools/docs/**:read,call'

精确 scope 语法、expiry、disable 和 register-path 参数以当前 tb sk --help 为准。不要用 Admin SK 作为所有服务的通用凭证。

设计业务身份和上游凭证前，分别阅读权限、SK 与可见性与密钥、出站身份与安全边界。

成功证据

tb whoami 显示正确 BaseURL、profile 和认证状态，SK 被遮蔽；
tb status --json 返回可解析对象，但随后仍需通过 tb help 和真实调用验证数据面；
tb help <path> --json 与直接 HTTP Accept: application/json 语义一致；
受限 SK 只能看见获准路径；缺 read 的路径表现为 404；
脚本在错误时收到非零退出码，--json 输出保持可解析。

常见失败

现象	处理
missing base URL/SK	传环境变量，选择正确 profile，或重新 `tb login`
401 `permission_denied`	SK 缺失、未知、禁用或过期；不要无限重试
404	路径不存在或当前身份不可见；从父路径 `tb help/tree` 开始排查
403	路径可见，但缺当前动作，例如 `call`/`write`/`admin`
`invalid_argument`	先运行该命令 `--help` 和节点 `~help --json`，不要依赖旧示例
`unavailable`	宿主能力、Secret、设备、Plugin 或上游暂不可用；根据 retryable、dispatch certainty 和错误来源处理，不能把任意设备失败自动入队
`tb search` 404	宿主未启用 Search，改用 tree/help
JSON quoting 失败	用 `--args-file -` 走 stdin，或标量用 `--arg key=value`；嵌套结构仍用 `--args`，不要叠加多个来源

Profile 与操作回滚

tb use 切换的是本机当前 profile，不会修改网关：

tb use
tb use team-a
tb whoami

资源删除命令只做名称承诺的动作。例如卸载集成不会自动删 Secret；先验证依赖，再显式执行对应 rm。CLI 严格区分节点、凭证、Plugin、allowlist 等资源，避免一个 convenience flag 造成级联删除。

执行管理操作前可先加 --json 获取资源标识并保存审计证据。pre-launch 升级前备份宿主状态，按发布说明逐项验证，不依赖隐藏旧 flag。

在容器和 CI 中使用

一次性命令使用环境 Secret；要复用 tb login profile 时才挂载配置 volume。tb connect 作为前台进程运行，由容器 restart policy 或 Kubernetes 重启；CLI 自己负责网络重连。

镜像架构、musl/glibc 和 CA 证书要求随发布产物变化，使用前查看对应版本的 CLI 容器文档，不从本站复制固定镜像标签。

下一步

想看同一 API 的图形界面：阅读Dashboard；
建立 Agent 的发现习惯：阅读发现、反馈与协作；
编写 HTTP 客户端：查看运行时 HTTP 参考；
所有精确参数以本机 tb --help、tb <command> --help 为准；
CLI、profile 或自动化异常：进入故障排查与升级。