Ghost 数据管道中的 Tinybird CLI 实战指南：tb 命令工作流、构建部署与本地开发

2026-09-07 16:43:37作者：魏侃纯Zoe

本篇基于 Ghost 仓库中的 Agent 技能文档 SKILL.md 及其配套的 11 份规则文件，系统讲解 Tinybird CLI（tb）在 CLI 4.0 下的核心工作流：如何用 dev_mode 配置驱动 tb build / tb deploy、如何在 Tinybird Local 与 Cloud 分支之间选择开发模式、如何编排 CI/CD 流水线，以及数据追加、替换、删除、Token 与 Secrets 管理的完整命令参考。读完本文，你能够独立搭建 Tinybird 本地开发环境、完成一次安全的生产部署，并理解 Ghost 仓库中 Tinybird 服务容器的实际接线方式。

一、这套规范的定位：Ghost 如何管理 Tinybird 项目

Ghost 的站点分析（analytics）数据管道构建在 Tinybird 之上。仓库中 SKILL.md 是一份面向开发者和 AI Agent 的操作规范，它把 Tinybird CLI 的正确用法固化为可执行规则，避免"凭记忆敲命令"带来的错误。

文档列出了规范的适用场景（When to Apply），涵盖以下十类操作：

运行任何 tb 命令；
选择开发工作流（local、branch 或 cloud）；
基于 Tinybird Local 的本地开发；
基于 Tinybird Cloud 分支的分支开发；
构建与部署项目；
搭建 CI/CD 流水线；
追加、替换或删除数据；
通过 CLI 管理 Token 和 Secrets；
生成 Mock 数据；
运行测试。

规范由一个入口文件加 11 份规则文件组成，全部位于 .agents/skills/tinybird-cli-guidelines/ 目录下：

规则文件	覆盖主题
development-workflows.md	三种开发工作流的选型对比
cli-commands.md	全量命令与标志位速查
build-deploy.md	CLI 4.0 的 build/deploy 行为与破坏性操作
local-development.md	Tinybird Local 命令、工作流与排障
branch-development.md	Cloud 分支、`--last-partition`、分支 Token
ci-cd.md	CI/CD 集成与预览环境
data-operations.md	数据替换与删除
append-data.md	三种数据追加方式
mock-data.md	Mock 数据生成流程
tokens.md	资源级 Token 与 JWT Token
secrets.md	Secrets 语法与 `tb secret` 命令

其中 cli-commands.md 开篇有一条最高优先级铁律：绝不臆造命令或标志位。不确定某个命令或 flag 是否存在时，先运行 tb <command> --help 验证，只使用文档中有记录或通过 --help 确认过的命令。

二、CLI 4.0 核心工作流：一次配置 `dev_mode`，之后只用裸命令

SKILL.md 的 Quick Reference 与 build-deploy.md 定义了 CLI 4.0 的标准姿势：

在 tinybird.config.json 中一次性配置 dev_mode（取值 branch、local 或 manual）；
运行 tb build 校验项目并同步到配置的开发目标环境；
运行 tb deploy 部署到 Tinybird Cloud 的 main（生产）。

关键行为规则：

tb build 的目标由 dev_mode 决定：
- dev_mode=local：构建到 Tinybird Local；
- dev_mode=branch：构建到由当前 git 分支自动派生的 Cloud 分支（不存在时自动创建）；
- dev_mode=manual：必须显式传 --local、--cloud 或 --branch 选择环境；
- 分支模式下，从 main/master 构建会被阻断，防止误改生产。
tb deploy 只应把文件部署到 Tinybird Cloud main（生产），并且只在用户明确请求生产部署时使用，部署前应征得确认。
--cloud / --local / --branch 只能作为显式的手动覆盖（override），平时不应出现。
用 tb info 检查当前 CLI 上下文。
build 和 deploy 是两个独立操作：tb build 之后不能假设生产环境已更新。

Deploy Check：先校验再部署

tb deploy --check 可以在不实际创建部署的情况下完成校验，尽早暴露 schema/依赖问题。凡是部署意图不明确时，都应先跑 check 模式：

tb deploy --check

破坏性操作：`--allow-destructive-operations`

在本地删除 datasources、pipes 或 connections 后，需要一次显式的破坏性部署才能生效：

tb deploy --allow-destructive-operations

规范对此有严格约束：只有当用户确认删除或数据丢失可接受时才使用该 flag；如果部署输出中出现关于删除的警告，先停下来请求确认，再带 flag 重跑。对应的禁令清单（What not to do）：

不要在缺少 --allow-destructive-operations 且无用户明确确认的情况下部署破坏性变更；
不要在 tb build 之后假设生产已更新。

三、三种开发工作流对比

development-workflows.md 给出了三种工作流的选型对比表，这是全文档最有决策价值的内容之一：

工作流	最适合	依赖	数据来源
Local（`dev_mode=local`）	单人开发、快速迭代、离线工作	Docker	Fixtures 或手动追加
Branch（`dev_mode=branch`）	团队协作、类生产测试	Cloud workspace	可选从生产复制
Cloud 直连	简单项目、快速原型	Cloud workspace	生产数据

推荐：Branch 工作流

对多数项目推荐使用 dev_mode=branch——它提供由 Tinybird Cloud 支撑的隔离环境，并可按需访问生产数据：

{
  "dev_mode": "branch"
}

完整流程五步：

为功能创建 git 分支；
运行 tb dev——Cloud 分支会按 git 分支名自动创建，文件变更被监听并自动重建；
开发与测试：tb endpoint data <pipe_name>；
推送并创建 PR——CI 运行 tb --cloud deploy --check；
合并——CD 运行 tb --cloud deploy。

Local 工作流

dev_mode=local 适合不依赖网络的快速迭代，尤其适合开发 SQL 逻辑并用 fixture 数据测试：

{
  "dev_mode": "local"
}

流程五步：

tb local start 启动 Tinybird Local；
新终端运行 tb dev——监听文件并自动重建；
追加测试数据：tb datasource append <name> --file fixtures/<name>.ndjson；
测试端点：tb endpoint data <pipe_name>；
就绪后部署：tb --cloud deploy。

Cloud 直连工作流

简单项目或快速原型可直接对 Cloud 工作。直接部署用：

tb --cloud deploy

偏好显式确认时，使用两步流程：

tb --cloud deployment create --wait
tb --cloud deployment promote

选型速查

新项目起步？先用 Local 快速搭起来，需要生产数据或团队协作时切到 Branch；
团队共享 workspace？用 Branch，每个开发者得到隔离环境；
快速原型或 demo？Cloud 直连即可；
CI/CD 流水线？CI 里用 Tinybird Local 做构建/测试，生产用 tb --cloud deploy。

测试端点：用 `tb endpoint data`，不是 `tb pipe data`

文档反复强调：用 tb endpoint data 测试端点，不要用 tb pipe data。endpoint data 命令会以 API 消费者的身份调用端点，包含参数校验与输出格式化：

tb endpoint data my_endpoint
tb endpoint data my_endpoint --start_date 2024-01-01 --end_date 2024-01-31

四、Tinybird Local：本地开发、UI 连接与排障

local-development.md 说明 Tinybird Local 以 Docker 容器形式运行，由 tb CLI 管理。核心命令与选项：

tb local start，可选参数：--use-aws-creds、--volumes-path <path>、--skip-new-version、--user-token、--workspace-token、--daemon；
tb local stop / tb local restart（restart 额外支持 --use-aws-creds、--volumes-path、--skip-new-version、--yes）；
tb local status、tb local remove、tb local version、tb local generate-tokens。

两个注意点：

若在没有持久化卷的情况下移除容器，本地数据会丢失；需要跨重启保留数据时用 --volumes-path。
手动 flag（--local、--cloud、--branch）依然有效，作为 dev_mode 的覆盖手段。

Local-First 工作流

tb local start；
将 tinybird.config.json 的 dev_mode 设为 local；
新终端运行 tb dev——监听文件变更并自动重建 Data Sources 和 Endpoints；
本地测试端点/查询：tb endpoint data <pipe_name>；
仅当用户明确要求生产部署时才运行 tb deploy。

tb dev 是推荐的开发命令：它监听项目文件，在检测到 Data Source 或 Endpoint 变更时自动重建。

连接 Tinybird UI

tb dev --ui：以 watch 模式构建，并把本地项目连接到 Tinybird UI，便于可视化探查与调试；
tb open：在浏览器中打开 workspace。

两者适合可视化检查查询结果、探查 Data Source schema 或调试 pipe 逻辑。

排障清单

status 显示 unhealthy → tb local restart 后重新检查；
认证未就绪 → 等待或重启容器；
status 出现内存警告 → 提高 Docker 内存分配；
Local 未运行 → tb local start。

五、分支开发：`--last-partition`、`--with-connections` 与分支 Token

branch-development.md 描述 Tinybird Cloud 分支机制：每个分支拥有独立的资源副本，并可按需包含生产数据，是团队协作场景的推荐工作流。

适用场景：

需要真实生产数据形态来测试功能；
多人协作在同一 workspace 工作；
部署前测试 schema 变更或新端点；
在 PR 上验证变更的 CI/CD 流程。

单人快速迭代时，Tinybird Local（dev_mode=local）可能更快。

分支工作流与创建方式

标准流程：创建 git 分支 → tb dev（自动创建同名 Cloud 分支并监听文件）→ 开发测试 → 推送建 PR → 合并即部署生产。

创建分支有两种方式：

自动（推荐）：checkout git 分支后运行 tb dev 或 tb build，Tinybird 自动创建/复用同名 Cloud 分支；
手动：tb branch create my_feature。

注意：分支名必须使用下划线而不是连字符（my_feature 而非 my-feature）。

`--last-partition`：把生产数据带进分支

tb branch create my_feature --last-partition

该 flag 会把生产的最新数据分区复制进分支，适合需要真实数据测试查询、验证端点行为或排查依赖生产数据形态的问题。不带它，分支从空开始。

`--with-connections`：启用连接器

tb branch create my_feature --last-partition --with-connections

用于在分支中启用 Kafka、S3、GCS 连接器。分支内 S3/GCS 连接器需用 tb --branch=my_feature datasource sample <datasource> --wait 导入样例数据；Kafka 连接默认停止，需显式启动：tb --branch=my_feature datasource start <datasource>。

分支 Token：让客户端应用无代码切换环境

创建分支后，可用其 token 让仪表盘、API、脚本等客户端连接分支环境而非生产环境：

tb --branch my_feature token ls

推荐模式是在应用里设置环境变量，优先使用分支 token，否则回落到生产 token：

# .env.local
TINYBIRD_API_URL=https://api.tinybird.co
TINYBIRD_API_TOKEN=<production-read-token>
TINYBIRD_BRANCH_TOKEN=<branch-token>

token = TINYBIRD_BRANCH_TOKEN || TINYBIRD_API_TOKEN

这样只需设置/取消分支 token 即可在分支数据与生产数据之间切换，无需改代码。

显式指定分支

大多数命令都可用 --branch flag 指向特定分支：

tb --branch my_feature endpoint data my_endpoint
tb --branch my_feature sql "SELECT count() FROM my_datasource"
tb --branch my_feature token ls

当 dev_mode=branch 时，tb build 会自动指向对应分支，无需 --branch。分支命令参考：

tb branch ls：列出所有分支；
tb branch create <name>：创建新分支（空）；
tb branch create <name> --last-partition：带最新生产数据创建；
tb branch create <name> --last-partition --with-connections：带数据与连接器创建；
tb branch rm <name>：删除分支；
tb branch clear：清除分支状态；
tb dev：启动开发会话（按 git 分支名自动建分支、监听文件）；
tb --branch <name> open：在 Tinybird UI 中打开分支。

六、CI/CD 集成：Tinybird Local 构建 + Cloud 校验

ci-cd.md 给出的推荐模式：CI 中用 Tinybird Local 构建和测试（tb --local build、tb --local test run），再用 tb --cloud deploy --check 对 Cloud 做部署前校验；CD 中在 main 分支合并后运行 tb --cloud deploy。

CI：PR 校验三步

tb --local build——对 Tinybird Local 构建项目；
tb --local test run——对 Tinybird Local 运行测试；
tb --cloud deploy --check——在 Cloud 上做一次 dry run 校验。

deploy --check 一步能在到达生产之前捕获 schema 兼容性、依赖解析与资源命名问题。

CD：生产部署

在变更合并到 main 分支时运行：

tb --cloud deploy

它会创建 staging deployment、迁移数据并提升到线上。偏好显式确认的项目用两步：

tb --cloud deployment create --wait
tb --cloud deployment promote

示例一：GitHub Actions

CI 工作流（PR 触发，仅 Tinybird 目录变更时运行，Tinybird Local 作为 service 容器）：

# .github/workflows/tinybird-ci.yml
name: Tinybird CI
on:
  pull_request:
    paths:
      - 'tinybird/**'

env:
  TINYBIRD_HOST: https://api.tinybird.co
  TINYBIRD_TOKEN: ${{ secrets.TB_ADMIN_TOKEN }}

jobs:
  validate:
    runs-on: ubuntu-latest
    services:
      tinybird:
        image: tinybirdco/tinybird-local:latest
        ports:
          - 7181:7181
    steps:
      - uses: actions/checkout@v4
      - name: Install Tinybird CLI
        run: curl https://tinybird.co | sh
      - name: Build project
        run: tb --local build
        working-directory: tinybird
      - name: Test project
        run: tb --local test run
        working-directory: tinybird
      - name: Deployment check
        run: tb --cloud --host ${{ env.TINYBIRD_HOST }} --token ${{ env.TINYBIRD_TOKEN }} deploy --check
        working-directory: tinybird

CD 工作流（main 分支 push 触发）：

# .github/workflows/tinybird-cd.yml
name: Tinybird CD
on:
  push:
    branches: [main]
    paths:
      - 'tinybird/**'

env:
  TINYBIRD_HOST: https://api.tinybird.co
  TINYBIRD_TOKEN: ${{ secrets.TB_ADMIN_TOKEN }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Tinybird CLI
        run: curl https://tinybird.co | sh
      - name: Deploy
        run: tb --cloud --host ${{ env.TINYBIRD_HOST }} --token ${{ env.TINYBIRD_TOKEN }} deploy
        working-directory: tinybird

示例二：GitLab CI

tinybird_ci:
  image: ubuntu:latest
  stage: test
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      changes:
        - tinybird/**
  services:
    - name: tinybirdco/tinybird-local:latest
      alias: tinybird-local
  before_script:
    - apt update && apt install -y curl
    - curl https://tinybird.co | sh
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - cd tinybird
    - tb --local build
    - tb --local test run
    - tb --cloud --host $TINYBIRD_HOST --token $TINYBIRD_TOKEN deploy --check

tinybird_cd:
  image: ubuntu:latest
  stage: deploy
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      changes:
        - tinybird/**
  before_script:
    - apt update && apt install -y curl
    - curl https://tinybird.co | sh
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - cd tinybird
    - tb --cloud --host $TINYBIRD_HOST --token $TINYBIRD_TOKEN deploy

预览环境：每个 PR 一个带生产数据的临时分支

预览环境为每个 pull request 创建一个临时 Tinybird 分支，让你合并前用生产数据测试变更。

用 SDK（@tinybirdco/sdk / tinybird-sdk）：tinybird preview 命令（注意它在 SDK 中，不在 tb CLI 中）会创建名为 tmp_ci_<git-branch> 的分支、构建资源并部署：

- run: npx tinybird preview
  env:
    TINYBIRD_TOKEN: ${{ secrets.TINYBIRD_TOKEN }}

SDK 会自动检测 CI 环境（GitHub Actions、GitLab CI、Vercel、CircleCI、Azure Pipelines、Bitbucket Pipelines）并解析正确的分支 token，host 从 token 推断。同名分支已存在时会被删除重建。

用 tb CLI 手动创建：tb 没有 preview 子命令，需手动建分支：

- name: Create preview branch
  run: tb --host ${{ env.TINYBIRD_HOST }} --token ${{ env.TINYBIRD_TOKEN }} branch create tmp_ci_${{ github.head_ref }} --last-partition
- name: Build on branch
  run: tb --host ${{ env.TINYBIRD_HOST }} --token ${{ env.TINYBIRD_TOKEN }} --branch=tmp_ci_${{ github.head_ref }} build

PR 关闭时清理：

# SDK
- run: npx tinybird branch delete tmp_ci_${{ github.head_ref }}

# tb CLI
- run: tb --host ${{ env.TINYBIRD_HOST }} --token ${{ env.TINYBIRD_TOKEN }} branch rm tmp_ci_${{ github.head_ref }}

带连接器的预览：tinybird preview 不会在预览分支中从连接器摄取数据。需要用 --with-connections 手动建分支：

tb branch create tmp_ci_my_feature --last-partition --with-connections

S3/GCS 连接器导入样例数据：

tb --branch=tmp_ci_my_feature datasource sample my_datasource --wait

Kafka 在预览分支中默认停止，显式启动：

tb --branch=tmp_ci_my_feature datasource start my_kafka_datasource

CI/CD 关键原则

生产部署应通过 CI/CD 进行，而非手动；
CI 用 Tinybird Local 构建/测试，再 tb --cloud deploy --check 校验 Cloud；
CD 流水线中使用 --wait，让 job 反映真实部署结果；
管理 token 存为 CI/CD secret，绝不写进代码；
CI 触发器限定到 Tinybird 项目文件路径，避免无谓运行；
需要每个 PR 完整可用分支（带生产数据）时，使用预览环境。

七、数据操作：追加、替换与删除

数据操作分两个文档：append-data.md 讲追加，data-operations.md 讲替换与删除。

追加数据的三种方式

tb datasource append 支持本地文件、远程 URL、事件载荷三种来源：

tb datasource append [datasource_name] --file /path/to/local/file

tb datasource append [datasource_name] --url https://example.com/data.csv

tb datasource append [datasource_name] --events '{"a":"b", "c":"d"}'

要点：命令是追加到已存在的 datasource；要指向 Cloud 用 tb --cloud datasource append（默认是 Local）。从 Kafka/S3/GCS 摄取数据走 connectors 体系。另外也可直接对 v0/events（流式）与 v0/datasources（批量）端点发 POST 请求。

选择性删除：`tb datasource delete`

删除匹配 SQL 条件的行：

tb datasource delete events --sql-condition "toDate(date) >= '2019-11-01' AND toDate(date) <= '2019-11-30'"

异步执行（返回 job ID），加 --wait 可阻塞至完成；
不会级联到下游 Materialized Views——MV 需单独删除；
需要 ADMIN token 权限；
活跃摄取数据期间可以安全执行。

清空 Data Source：`tb datasource truncate`

删除 Data Source 全部行：

tb datasource truncate events

加 --cascade 会同时清空通过 Materialized Views 挂载的依赖 Data Sources。

选择性替换（Partial Replace）

只替换匹配条件的数据：

tb datasource replace events data.csv --sql-condition "toDate(date) >= '2019-11-01' AND toDate(date) <= '2019-11-30'"

关键约束（Critical）：绝不要在活跃摄取的分区上执行替换，可能丢失操作期间插入的数据。

规则：

SQL 条件中必须包含分区键（partition key）；
条件同时决定：(1) 对哪些分区操作，(2) 新数据中哪些行被追加；
会自动级联到下游 Materialized Views（所有 MV 必须有兼容的分区键）；
新数据 schema 必须与现有 Data Source 完全一致。

为什么分区键重要：若 Data Source 使用 ENGINE_PARTITION_KEY "country"，而执行：

tb datasource replace events data.csv --sql-condition "status='active'"

替换过程会用 payload 行来识别分区，这个条件不会按预期工作——条件必须匹配分区键。

完全替换（Full Replace）

不带 --sql-condition 即替换整个 Data Source 内容：

tb datasource replace events data.csv

关键约束：活跃摄取期间不要运行，可能丢数据。

八、测试与 Mock 数据

测试命令

tb test run：运行完整测试套件；
tb test run <file_or_test>：运行指定测试文件或测试；
tb test update <file_or_test>：更新测试期望值。

Mock 数据生成流程

cli-commands.md 指出 tb mock 已在 CLI 4.0 中移除，mock-data.md 给出了替代流程——用 fixtures/ 目录加追加命令生成样例数据：

构造一个返回 mock 行的 SQL 查询；
本地执行并限制行数、格式化：tb --output=json|csv '<sql>' --rows-limit <rows>；
预览生成的输出；
确认在 fixtures/ 下创建 fixture 文件；
写入 fixtures/<datasource_name>.ndjson 或 fixtures/<datasource_name>.csv；
确认追加；
将 fixture 追加到 Tinybird Local 中的 datasource。

示例 Mock 查询：

SELECT
    rand() % 1000 AS experience_gained,
    1 + rand() % 100 AS level,
    rand() % 500 AS monster_kills,
    concat('player_', toString(rand() % 10000)) AS player_id,
    rand() % 50 AS pvp_kills,
    rand() % 200 AS quest_completions,
    now() - rand() % 86400 AS timestamp
FROM numbers(ROWS)

注意事项：查询必须通过 FROM numbers(ROWS) 恰好返回 ROWS 行；Mock 查询本身不要加 FORMAT 子句或结尾分号。

错误处理：

若 datasource 处于 quarantine（隔离）状态，查询 <datasource_name>_quarantine 并展示前 5 行；
若追加报 "must be created first with 'mode=create'"，重建项目后重试。

九、Token 与 Secrets 管理

Token：资源级声明 + JWT

tokens.md 区分两类 token：

资源级 token 直接声明在 datafiles 中，Tinybird 会跟踪并随 datafile 内容更新 token：

DATASOURCES:READ:datasource_name → .datasource 文件中的 TOKEN <token_name> READ；
DATASOURCES:APPEND:datasource_name → .datasource 文件中的 TOKEN <token_name> APPEND；
PIPES:READ:pipe_name → .pipe 文件中的 TOKEN <token_name> READ。

示例：

TOKEN app_read READ
TOKEN landing_append APPEND

运维型 token（不绑定资源）通过 CLI 创建：

tb token create static new_admin_token --scope <scope>

可用 scope：TOKENS、ADMIN、ORG_DATASOURCES:READ、WORKSPACE:READ_ALL。

JWT token 有 TTL，只能使用 PIPES:READ 或 DATASOURCES:READ scope，面向最终用户调用端点/读取 datasource 而不暴露主 API key：

tb token create jwt my_jwt_token --ttl 1h --scope PIPES:READ --resource my_pipe

带过滤条件的 datasource 读：

tb token create jwt my_jwt_token --ttl 1h --scope DATASOURCES:READ --resource my_datasource --filter "column = 'value'"

多 scope 多资源（数量必须匹配），PIPES:READ 可带固定参数：

tb token create jwt my_jwt_token --ttl 1h \
  --scope PIPES:READ --resource my_pipe --fixed-params "k1=v1,k2=v2" \
  --scope DATASOURCES:READ --resource my_datasource --filter "column = 'value'"

CLI 侧还有 tb token ls 列出所有 token。

Secrets

secrets.md 定义了文件内使用 secrets 的语法：

{{ tb_secret("SECRET_NAME", "DEFAULT_VALUE_OPTIONAL") }}

规则：

连接（connections）与 pipe SQL 中的凭据使用 secrets；
pipe 文件中的 secret 不允许默认值；连接文件中的 secret 可以带默认值；
需要 secret 时，不要把它替换成动态参数。

CLI 命令：

tb secret ls
tb secret ls --match _test
tb secret set SECRET_NAME SECRET_VALUE
tb secret set SECRET_NAME        # 安全提示输入
tb secret set SECRET_NAME --multiline   # 打开编辑器
tb secret rm SECRET_NAME

本地 secret：存在 .env.local 文件时，其中的 secret 会在 Tinybird Local 中被自动加载。

十、完整命令速查

以下为 cli-commands.md 的全量命令参考。

全局覆盖

tb --cloud <command>：对 Cloud 执行命令；
tb --local <command>：对 Local 执行命令；
tb --branch <branch_name> <command>：对指定分支执行命令；
tb --debug <command>：打印调试信息。

项目与开发

tb init：初始化新项目；
tb create：tb init 的弃用别名；
tb info：显示项目信息与 CLI 上下文；
tb build：校验并构建项目；
tb build --watch：构建并监听变更；
tb dev：构建并监听变更；
tb dev --ui：将本地项目连接到 Tinybird UI；
tb preview：为当前分支创建/更新预览环境；
tb open：在浏览器中打开 workspace；
tb fmt <file>：格式化 .datasource、.pipe 或 .connection 文件；
tb fmt <file> --diff：仅显示 diff，不修改文件。

部署

tb deploy：部署项目；
tb deploy --check：只校验不创建部署；
tb deploy --wait：等待部署完成；
tb deploy --allow-destructive-operations：允许破坏性变更（需显式确认）；
tb deployment ls：列出所有部署；
tb deployment create：创建 staging 部署并在提升前校验；
tb deployment promote：将 staging 部署提升到生产；
tb deployment discard：丢弃待处理部署。

日志

tb logs：显示常用服务 datasource 的近期日志；
tb logs --start -30m --source '*'：自定义时间范围查询全部 source；
tb logs --output json：以 JSON 输出日志便于脚本处理。

Data Sources

tb datasource ls：列出所有数据源；
tb datasource append <name> --file <path> / --url <url> / --events '<json>'：三种方式追加数据；
tb datasource replace <name> <file_or_url>：全量替换；
tb datasource replace <name> <file_or_url> --sql-condition "<condition>"：选择性替换；
tb datasource delete <name> --sql-condition "<condition>"：删除匹配行；
tb datasource delete <name> --sql-condition "<condition>" --wait：删除并等待完成；
tb datasource truncate <name> --yes：删除全部行；
tb datasource truncate <name> --cascade --yes：级联清空含依赖 MV；
tb datasource sync <name> --yes：从 S3/GCS 连接同步；
tb datasource export <name> --format csv：导出数据到文件。

Pipes 与 Endpoints

tb pipe ls：列出所有 pipes；
tb endpoint ls：列出所有 endpoints；
tb endpoint data <pipe_name>：获取端点数据（测试端点就用它，不要用 tb pipe data）；
tb endpoint data <pipe_name> --param_name value：带参数获取数据；
tb endpoint stats <pipe_name>：显示最近 7 天端点统计；
tb endpoint url <pipe_name>：打印端点 URL；
tb endpoint token <pipe_name>：获取读取端点的 token。

SQL 查询

tb sql "<query>"：执行 SQL；
tb sql "<query>" --stats：执行并显示统计；
tb sql --pipe <path> --node <node_name>：从指定 pipe 节点执行 SQL。

Materializations 与 Copy Pipes

tb materialization ls：列出所有物化视图；
tb copy ls：列出所有 copy pipes；
tb copy run <pipe_name>：手动运行 copy pipe；
tb copy run <pipe_name> --param key=value：带参数运行。

Tinybird Local

tb local start / tb local stop / tb local restart --yes；
tb local status / tb local remove / tb local version / tb local clear。

Workspace

tb workspace ls：列出所有 workspace；
tb workspace current：显示当前 workspace；
tb workspace clear --yes：清除 workspace 状态。

认证

tb login：通过浏览器认证；
tb logout：移除认证；
tb update：更新 CLI 到最新版。

其余分支（tb branch ls/create/rm/clear）、测试（tb test run/update）、Token 与 Secret（tb token ls、tb secret ls/set/rm）、连接与 Sink（tb connection ls、tb sink ls）、作业（tb job ls、tb job cancel <job_id>）命令见上文对应章节。

十一、Ghost 仓库中的真实接线：从 Dockerfile 到 e2e

规范文档不是纸上谈兵——Ghost 仓库中有多处可直接对照的实现证据。

容器化的 CLI 环境：docker/tb-cli/Dockerfile 基于 Python 3.13 镜像安装 Tinybird CLI，并刻意将版本固定在 4.6.13——Dockerfile 中的注释说明 4.6.14 会把嵌套 JSON 对象以 ClickHouse Tuple 语法而非原始 JSON 写入 String 列，导致对 analytics_events.payload 做 JSONExtractString 返回空串，因此通过 Renovate 与镜像 pin 双重手段锁版本。这说明 SKILL.md 中"以当前仓库实际内容为准"的原则是实际发生过版本回归后的经验教训。

开发环境的自动接线：docker/tb-cli/entrypoint.sh 实现了文档中 Local 工作流的自动化版本：先执行 tb --local build 构建 Tinybird 文件，再运行 tb --output json info 解析出 local.workspace_id 与 local.token，把结果写入 /ghost/core/core/server/data/tinybird 下的 .env 文件，供 Ghost 核心与 Analytics 服务自动配置到 Tinybird Local 的连接。这与 compose.dev.analytics.yaml 中 analytics 服务的 PROXY_TARGET=http://tinybird-local:7181/v0/events 配置相互印证——Ghost 本地分析链路正是走 Tinybird Local 容器的 7181 端口。

E2E 基础设施：e2e 目录把 tinybird-local 与 tb-cli 列为标准基础设施服务（见 e2e/scripts/infra-up.sh 与 e2e/scripts/infra-down.sh），e2e/scripts/sync-tinybird-state.mjs 则负责在测试容器与宿主之间同步 Tinybird 的 .env.tinybird 配置状态，保证 Playwright 容器能复用宿主机 Tinybird Local 的 workspace 凭据。从这些脚本的结构可以推断，Ghost 的 E2E 测试同样遵循规范中"CI 用 Tinybird Local 构建测试、token 走 secret"的原则。

十二、规范要点回顾

配置一次，命令保持干净：dev_mode 决定 tb build 的目标，tb deploy 永远指向生产；flag 只做显式覆盖。
测试端点用 tb endpoint data，它以消费者视角完成参数校验与输出格式化。
破坏性变更双保险：--allow-destructive-operations + 用户显式确认。
替换数据必须带分区键条件，且避免在活跃摄取的分区上操作。
生产部署交给 CI/CD：Local 构建测试 → deploy --check 校验 → 合并后 deploy，token 存 secret。
不确定就 --help：绝不臆造命令和标志位。