使用 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 会明确拒绝。

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

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

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

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

调用支持两种形态：

# 具体工具路径，第二个 positional 是 arguments JSON
tb call tools/docs/search '{"query":"tool-bridge"}'

# 通用节点信封，适合 builtin/context/device 等所有 kind
tb call system/status --tool get
tb call tools/docs --tool search --args '{"query":"tool-bridge"}'

arguments 只能来自 positional JSON、--args 或 --args-file 之一。复杂或敏感输入使用文件/stdin 对应命令，避免 shell quoting 和 history 泄露。

常用任务地图

任务	命令族	动态真源
浏览树和契约	tb ls/tree/help/search	目标路径 ~help、可选 ~search
调用工具	tb call	工具级 tb help <path>/<tool> --json
管理 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 mount fs	tb connect --help、设备路径 ~help
联邦	tb federation、tb server	system/federation、remote 节点 ~help
协作经验	tb feedback、tb note	路径 ~feedback 与 ~help
外部 Plugin	tb plugin	system/plugin 与 Plugin ~describe

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 和错误来源处理
tb search 404	宿主未启用 Search，改用 tree/help
JSON quoting 失败	使用 --args-file，不要叠加 positional/--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 或自动化异常：进入故障排查与升级。