Apitally CLI 用于从 Apitally 获取数据，并可选地写入本地 DuckDB 以便用 SQL 调查。主要数据源有三类：指标为预聚合数据（请求数、错误率、响应时间分位、吞吐量），保留 30 天 1 分钟粒度、13 个月 30 分钟粒度；请求日志为单个 API 请求记录，含方法、URL、状态码、响应时间、消费者、请求头、负载、异常和 trace ID，保留 15 天；追踪为单个操作（如数据库查询、外部调用）的 span，含耗时、状态、属性和事件，可用性取决于接入、配置与 span 保留策略。
使用方式：通过 npx @apitally/cli <command> [--api-key <key>] 运行，无需安装。需团队级 API Key；auth 命令将密钥保存到 ~/.apitally/auth.json，后续命令默认使用，可用 --api-key 覆盖。若命令退出码为 3 表示认证错误，需先运行 npx @apitally/cli auth 认证。列表结果与 SQL 查询默认以 NDJSON 输出到 stdout；加 --db 时拉取命令写入 DuckDB（默认 ~/.apitally/data.duckdb），再通过 sql 查询。常用命令包括 auth、whoami、apps、consumers、endpoints、metrics、request-logs、traces、request-details、sql、reset-db。
典型调查流程：先用 apps 确定 app_id，未指定时间范围时默认最近 7 天；必要时用 endpoints 发现方法与路径组合、用 consumers 映射 identifier 与 consumer_id；再按问题选择 metrics（聚合趋势、错误率、端点对比）、request-logs（单请求详情、异常、请求头、负载）或 traces（慢查询、外部调用、span 错误），可用 request-details 获取单请求完整视图。SQL 查询需按 app_id 及调查范围过滤：metrics 用 period_start，request-logs 用 timestamp，spans 用精确 trace_id 或 start_time_ns 整数边界。
限制与注意：request-logs 单次最多 1000000 行；traces 的 --since 在未加 trace_id 过滤时必填；过滤器筛选的是 span 而非整条 trace，采样、limit 与时间边界可能遗漏兄弟 span，不能把部分集合当作完整 trace 统计；请求或响应体超过 50 KB 时 SDK 不采集，值为 NULL；DuckDB 不支持 TIMESTAMPTZ 减 INTERVAL，需用 epoch 纳秒，日期截断需先 AT TIME ZONE 'UTC'；trace 与请求日志需按 app 和 trace ID 关联，而非 request UUID；若遇旧版数据库 schema 不兼容，可换新 --db 路径或在用户同意后执行 reset-db 并重新拉取。退出码 0 成功、1 未知错误、2 用法错误、3 认证错误、4 输入错误、5 API/网络错误。