bt CLI 用于在本地操作 Braintrust 的项目、trace、prompt 与同步状态。使用前可先运行 bt status、bt projects list 确认认证与上下文。常用查询命令包括 bt prompts list --project <name>、bt view logs --project <name>、bt view trace --object-ref <ref> --trace-id <id>，需要机器可读结果时加 --json。
评估：bt eval 递归发现并运行当前目录评估文件，可指定目录、glob 或多个文件；默认自动检测 JavaScript runner（tsx、vite-node、ts-node 等），也可用 --runner 指定。支持 --first 或 --sample 做抽样冒烟运行，-- 后的参数会转发给评估文件。
SQL：bt sql 在 TTY 下交互运行，否则非交互；查询需对 Braintrust 表函数使用 FROM，例如 project_logs(...)。分页用 OFFSET '<CURSOR>'，支持 WHERE，不支持 join、子查询、union 与窗口函数。
查看：bt view logs 列出日志，bt view span 获取单个 span 完整内容，支持 --limit、--cursor、--search、--filter、--window 等参数。
认证：bt auth login 支持 OAuth 或 API key，可用 --profile 指定配置；认证解析顺序为显式 --profile、--api-key 或 BRAINTRUST_API_KEY、BRAINTRUST_PROFILE、组织匹配、单配置自动选择、交互选择。
配置：bt setup 可安装 Claude、Codex、Copilot、Cursor、Gemini、OpenCode、Qwen 等代理技能、MCP 与工作流文档，bt docs fetch 同步文档。详细语法请用 bt --help 与各子命令 --help。