Tinybird Cli Guidelines

Tinybird CLI Guidelines

Guidance for using the Tinybird CLI (tb) for local development, deployments, data operations, and workspace management.

When to Apply

• Running any tb command
• Choosing a development workflow (local, branch, or cloud)
• Local development with Tinybird Local
• Branch development with Tinybird Cloud branches
• Building and deploying projects
• Setting up CI/CD pipelines
• Appending, replacing, or deleting data
• Managing tokens and secrets via CLI
• Generating mock data
• Running tests

Rule Files

• rules/development-workflows.md
• rules/cli-commands.md
• rules/build-deploy.md
• rules/local-development.md
• rules/branch-development.md
• rules/ci-cd.md
• rules/data-operations.md
• rules/append-data.md
• rules/mock-data.md
• rules/tokens.md
• rules/secrets.md

Quick Reference

• CLI 4.0 workflow: configure dev_mode once, then use plain tb build and tb deploy.
• tb build targets your configured development environment (branch or local) in tinybird.config.json.
• tb deploy targets Tinybird Cloud production.
• Use --cloud/--local/--branch only as explicit manual overrides.
• Use tb info to check CLI context.
• Use tb endpoint data <pipe> to test endpoints (not tb pipe data).
• Never invent commands or flags; run tb <command> --help to verify.

Append Data

Tinybird CLI supports three ways to append data to an existing datasource: local file, remote URL, or events payload.

CLI: tb datasource append

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"}'

Notes:

• The command appends to an existing datasource.
• Use tb --cloud datasource append to target Cloud; Local is the default.
• For ingesting data from Kafka, S3 or GCS, see: https://www.tinybird.co/docs/forward/get-data-in/connectors

You can also send POST request to v0/events (streaming) and v0/datasources (batch) endpoints.

Branch Development

Overview

Tinybird Cloud branches provide isolated environments for development and testing. Each branch gets its own copy of resources and can optionally include production data. Branches are the recommended workflow for teams collaborating on the same workspace.

When to Use Branches

• Developing features that need real production data shapes for testing
• Collaborating with a team where multiple people work on the same workspace
• Testing schema changes or new endpoints before deploying to production
• CI/CD workflows that validate changes on pull requests

For solo development or quick iteration, Tinybird Local (dev_mode=local) may be faster. See rules/local-development.md.

Branch Workflow

1. Create a git branch for your feature 2. Run tb dev — Tinybird automatically creates a Cloud branch matching your git branch name 3. Develop and test against the branch (file changes are watched and auto-rebuilt) 4. Push changes and create a PR 5. Merge to deploy to production

Creating Branches

Automatic (recommended):

Check out a git branch and run tb dev or tb build. Tinybird automatically creates or uses a Cloud branch with the same name as your git branch.

Manual:

tb branch create my_feature

Branch names must use underscores, not hyphens (e.g., my_feature, not my-feature).

The --last-partition Flag

Use --last-partition to copy the latest partition of production data into the branch:

tb branch create my_feature --last-partition

This is useful when you need real data to test queries, validate endpoint behavior, or debug issues that depend on production data shapes. Without it, the branch starts empty.

The --with-connections Flag

Use --with-connections to enable connectors (Kafka, S3, GCS) in the branch:

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

For S3/GCS, import sample data with tb --branch=my_feature datasource sample <datasource> --wait. Kafka connections are stopped by default and need to be started explicitly with tb --branch=my_feature datasource start <datasource>.

Working with Branch Tokens

After creating a branch, you may need its token to connect client applications (dashboards, APIs, scripts) to the branch environment instead of production.

List tokens for a branch:

tb --branch my_feature token ls

Using Branch Tokens in Client Apps

A common pattern is to set an environment variable that your application checks, falling back to the production token when no branch token is set:

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

In your application, prioritize the branch token when present:

token = TINYBIRD_BRANCH_TOKEN || TINYBIRD_API_TOKEN

This way, setting or unsetting the branch token switches between branch and production data without code changes.

Branch Commands Reference

• tb branch ls: List all branches
• tb branch create <name>: Create a new branch (empty)
• tb branch create <name> --last-partition: Create a branch with latest production data
• tb branch create <name> --last-partition --with-connections: Create a branch with data and connectors
• tb branch rm <name>: Remove a branch
• tb branch clear: Clear branch state
• tb dev: Start development session (auto-creates branch from git branch name, watches files)
• tb --branch <name> open: Open the branch in the Tinybird UI

Targeting a Branch Explicitly

Most commands can target a specific branch with the --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

When dev_mode=branch, tb build targets the branch automatically without needing --branch.

Build & Deploy

Use this rule to keep local files, development environments, and production deployments aligned under the CLI 4.0 workflow.

Default Workflow (CLI 4.0)

1. Configure dev_mode in tinybird.config.json (branch, local, or manual). 2. Run tb build to validate and sync to the configured development target. 3. Run tb deploy to deploy to Tinybird Cloud main (production).

In CLI 4.0, build/deploy should usually be run without --cloud, --local, or --branch.

tb build Behavior

• dev_mode=local: builds against Tinybird Local.
• dev_mode=branch: builds against a Cloud branch derived from the current git branch (created automatically if needed).
• dev_mode=manual: requires explicit flags (--local, --cloud, --branch) for environment selection.
• In branch mode, building from main/master is blocked to avoid accidental production changes.

tb deploy Behavior

• tb deploy deploys current project files to Tinybird Cloud main.
• Use only when the user explicitly requests a production deployment.
• Ask for confirmation before deploying.

Deploy Check

• Run tb deploy --check before real deploys to catch schema/dependency issues early.
• Use check mode whenever deployment intent is uncertain.

Destructive operations and flags

• Deleting datasources, pipes, or connections locally requires an explicit destructive deploy.
• Use tb deploy --allow-destructive-operations only when the user confirms deletion or data loss is acceptable.
• If you see warnings about deletions, stop and ask for confirmation before re-running with the flag.

Example:

tb deploy --allow-destructive-operations

Manual Overrides

• Explicit flags still work and override dev_mode.
• Use overrides only when the user explicitly asks for a specific environment target.

Validation intent (why)

• Building keeps development environments aligned with local files for fast iteration.
• Deploy checks reduce failed deployments by validating changes before publishing.

What not to do

• Do not deploy destructive changes without --allow-destructive-operations and explicit user confirmation.
• Do not assume production is updated after tb build; build and deploy are separate operations.

CI/CD Integration

Recommended Pattern

Use Tinybird Local in CI to build and test with tb --local build and tb --local test run, then tb --cloud deploy --check to validate against Cloud. In CD, use tb --cloud deploy to deploy on merge to the main branch.

CI: Pull Request Validation

The recommended CI flow uses a Tinybird Local service container for building and testing, then validates the deployment against Cloud:

1. tb --local build — build the project against Tinybird Local 2. tb --local test run — run tests against Tinybird Local 3. tb --cloud deploy --check — validate the deployment would succeed on Cloud (dry run)

The deploy --check step catches schema compatibility, dependency resolution, and resource naming issues before they reach production.

CD: Production Deployment

Run when changes are merged to the main branch:

tb --cloud deploy

This creates a staging deployment, migrates data, and promotes to live.

For projects that prefer explicit confirmation, use a two-step process:

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

Example: GitHub Actions

# .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

# .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

Example: 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

Preview Environments

Preview environments create an ephemeral Tinybird branch per pull request, so you can test changes with production data before merging.

Using the TypeScript or Python SDK

The tinybird preview command (available in @tinybirdco/sdk and tinybird-sdk, not the tb CLI) creates a branch named tmp_ci_<git-branch>, builds resources, and deploys them:

# GitHub Actions example
- run: npx tinybird preview
  env:
    TINYBIRD_TOKEN: ${{ secrets.TINYBIRD_TOKEN }}

The SDK auto-detects CI environments (GitHub Actions, GitLab CI, Vercel, CircleCI, Azure Pipelines, Bitbucket Pipelines) and resolves the correct branch token. The host is inferred from the token.

If a branch with the same name already exists, it is deleted and recreated.

Using the tb CLI

The tb CLI doesn't have a preview subcommand. Create preview branches manually:

- 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

Cleanup

Delete preview branches when the PR is closed:

# 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 }}

Preview with connectors

When your project uses Kafka, S3, or GCS connectors, the tinybird preview command doesn't ingest data from connectors in preview branches. To test with connector data, create the branch manually with --with-connections:

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

For S3/GCS connectors, import sample data:

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

Kafka connections are stopped by default in preview branches. Start them explicitly:

tb --branch=tmp_ci_my_feature datasource start my_kafka_datasource

Key Principles

• Production deploys should happen through CI/CD, not manually.
• Use Tinybird Local in CI for building and testing (tb --local build, tb --local test run), then tb --cloud deploy --check to validate against Cloud.
• Use --wait in CD pipelines so the job reflects the actual deployment result.
• Store the admin token as a CI/CD secret, never in code.
• Scope CI triggers to Tinybird project file paths to avoid unnecessary runs.
• Use preview environments when you need a full working branch per PR with production data.

Tinybird CLI Commands

⚠️ Never invent commands or flags. If you are unsure whether a command or flag exists, run tb <command> --help to verify before using it. Only use commands and flags documented here or confirmed via --help.

Build/Deploy Context (CLI 4.0)

• Preferred flow: configure dev_mode once, then run plain tb build and tb deploy.
• Use --cloud, --local, and --branch only as explicit manual overrides.

Global Overrides

• tb --cloud <command>: Run command against Cloud
• tb --local <command>: Run command against Local
• tb --branch <branch_name> <command>: Run command against a specific branch
• tb --debug <command>: Print debug information

Project & Development

• tb init: Initialize a new project
• tb create: Deprecated alias for tb init
• tb info: Show project information and CLI context
• tb build: Validate and build the project
• tb build --watch: Build and watch for changes
• tb dev: Build and watch for changes
• tb dev --ui: Connect local project to Tinybird UI
• tb preview: Create/update preview environment for the current branch
• tb open: Open workspace in the browser
• tb fmt <file>: Format a .datasource, .pipe, or .connection file
• tb fmt <file> --diff: Show diff without modifying file

Deploy & Deployments

• tb deploy: Deploy the project
• tb deploy --check: Validate deployment without actually creating
• tb deploy --wait: Wait for deployment to finish
• tb deploy --allow-destructive-operations: Allow destructive changes (requires explicit confirmation)
• tb deployment ls: List all deployments
• tb deployment create: Create a staging deployment and validate before promoting
• tb deployment promote: Promote a staging deployment to production
• tb deployment discard: Discard a pending deployment

Logs

• tb logs: Show recent logs from common service datasources
• tb logs --start -30m --source '*': Query all sources for a custom time range
• tb logs --output json: Emit logs as JSON for scripting

Data Sources

• tb datasource ls: List all data sources
• tb datasource append <name> --file <path>: Append data from local file
• tb datasource append <name> --url <url>: Append data from URL
• tb datasource append <name> --events '<json>': Append JSON events
• tb datasource replace <name> <file_or_url>: Full replace of data source
• tb datasource replace <name> <file_or_url> --sql-condition "<condition>": Selective replace
• tb datasource delete <name> --sql-condition "<condition>": Delete matching rows
• tb datasource delete <name> --sql-condition "<condition>" --wait: Delete and wait for completion
• tb datasource truncate <name> --yes: Delete all rows
• tb datasource truncate <name> --cascade --yes: Truncate including dependent MVs
• tb datasource sync <name> --yes: Sync from S3/GCS connection
• tb datasource export <name> --format csv: Export data to file

Pipes & Endpoints

• tb pipe ls: List all pipes
• tb endpoint ls: List all endpoints
• tb endpoint data <pipe_name>: Get data from endpoint (use this to test endpoints)
• tb endpoint data <pipe_name> --param_name value: Get data with parameters
• tb endpoint stats <pipe_name>: Show endpoint stats for last 7 days
• tb endpoint url <pipe_name>: Print endpoint URL
• tb endpoint token <pipe_name>: Get token to read endpoint

Note: use tb endpoint data to test endpoints, not tb pipe data. The endpoint data command calls the endpoint as a consumer would, with parameter validation and output formatting.

SQL Queries

• tb sql "<query>": Run SQL query
• tb sql "<query>" --stats: Run query and show stats
• tb sql --pipe <path> --node <node_name>: Run SQL from a specific pipe node

Materializations & Copy Pipes

• tb materialization ls: List all materializations
• tb copy ls: List all copy pipes
• tb copy run <pipe_name>: Run a copy pipe manually
• tb copy run <pipe_name> --param key=value: Run with parameters

Testing

• tb test run: Run the full test suite
• tb test run <file_or_test>: Run specific test file or test
• tb test update <file_or_test>: Update test expectations

Mock Data

• tb mock was removed in CLI 4.0
• Use the fixtures/ folder and agent skills to generate sample data, then append with tb datasource append

Tokens & Secrets

• tb token ls: List all tokens
• tb secret ls: List all secrets
• tb secret set <name> <value>: Create or update a secret
• tb secret rm <name>: Delete a secret

Connections & Sinks

• tb connection ls: List all connections
• tb sink ls: List all sinks

Jobs

• tb job ls: List all jobs
• tb job cancel <job_id>: Cancel a running job

Branches

• tb branch ls: List all branches
• tb branch create <name>: Create a new branch (starts empty)
• tb branch create <name> --last-partition: Create a branch with latest production data partition
• tb branch rm <name>: Remove a branch
• tb branch clear: Clear branch state
• tb --branch <name> token ls: List tokens for a specific branch
• tb --branch <name> endpoint data <pipe>: Test endpoint on a specific branch

Tinybird Local

• tb local start: Start Tinybird Local container
• tb local stop: Stop Tinybird Local
• tb local restart --yes: Restart Tinybird Local
• tb local status: Check Tinybird Local status
• tb local remove: Remove Tinybird Local completely
• tb local version: Show Tinybird Local version
• tb local clear: Clear local workspace state

Workspace

• tb workspace ls: List all workspaces
• tb workspace current: Show current workspace
• tb workspace clear --yes: Clear workspace state

Authentication

• tb login: Authenticate via browser
• tb logout: Remove authentication
• tb update: Update CLI to latest version

Data Operations (Replace & Delete)

Operations for updating and removing data from Data Sources.

Delete Data Selectively

Delete rows matching a SQL condition:

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

• Runs asynchronously (returns job ID); use --wait to block until complete
• Does not cascade to downstream Materialized Views—delete from MVs separately
• Requires ADMIN token scope
• Safe to run while actively ingesting data

Truncate Data Source

Delete all rows from a Data Source:

tb datasource truncate events

Use --cascade to also truncate dependent Data Sources attached via Materialized Views.

Replace Data Selectively (Partial Replace)

Replace only data matching a condition:

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

⚠️ Critical: Never replace data in partitions where you are actively ingesting. You may lose data inserted during the operation.

Rules:

• Always include the partition key in the SQL condition
• The condition determines: (1) which partitions to operate on, (2) which rows from new data to append
• Cascades automatically to downstream Materialized Views (all must have compatible partition keys)
• Schema of new data must match existing Data Source exactly

Why Partition Key Matters

If your Data Source uses ENGINE_PARTITION_KEY "country" and you run:

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

This will not work as expected—the replace process uses payload rows to identify partitions. Always match the partition key.

Replace Data Completely (Full Replace)

Replace entire Data Source contents (no --sql-condition):

tb datasource replace events data.csv

⚠️ Critical: Do not run while actively ingesting—you may lose data.

Development Workflows

Tinybird supports three development workflows. Choose based on your team size, infrastructure, and iteration speed needs.

Workflow Comparison

Recommended: Branch Workflow

For most projects, use dev_mode=branch. It provides isolated environments backed by Tinybird Cloud, with optional access to production data.

{
  "dev_mode": "branch"
}

1. Create a git branch for your feature 2. Run tb dev — a Cloud branch is created automatically from the git branch name, file changes are watched and auto-rebuilt 3. Develop and test: tb endpoint data <pipe_name> 4. Push, create PR — CI runs tb --cloud deploy --check 5. Merge — CD runs tb --cloud deploy

See rules/branch-development.md for details on branch tokens and --last-partition.

Local Workflow

Use dev_mode=local for fast iteration without network dependencies. Good for developing SQL logic and testing with fixture data.

{
  "dev_mode": "local"
}

1. Start Tinybird Local: tb local start 2. Run tb dev in a new terminal — watches files and auto-rebuilds 3. Append test data: tb datasource append <name> --file fixtures/<name>.ndjson 4. Test endpoints: tb endpoint data <pipe_name> 5. Deploy when ready: tb --cloud deploy

See rules/local-development.md for Tinybird Local commands and troubleshooting.

Cloud Direct Workflow

For simple projects or quick prototyping, you can work directly against Cloud. Use tb --cloud deploy to deploy, or the two-step process for explicit confirmation:

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

Or the combined shorthand:

tb --cloud deploy

Choosing a Workflow

• Starting a new project? Start with Local for fast bootstrapping, switch to Branch when you need production data or team collaboration.
• Team project with shared workspace? Use Branch. Each developer gets an isolated environment.
• Quick prototype or demo? Cloud direct is fine.
• CI/CD pipeline? Use Tinybird Local for CI build/test, then tb --cloud deploy for production. See rules/ci-cd.md.

Testing Endpoints

Use tb endpoint data to test endpoint output:

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

Use tb endpoint data, not tb pipe data. The endpoint data command calls the endpoint as an API consumer would, including parameter validation and output formatting.

Tinybird Local Development

Overview

• Tinybird Local runs as a Docker container managed by the Tinybird CLI.
• In CLI 4.0, tb build uses dev_mode from tinybird.config.json.
• Use Tinybird Local for fast local iteration (dev_mode=local), then deploy with tb deploy.

Commands

• tb local start
• Options: --use-aws-creds, --volumes-path <path>, --skip-new-version, --user-token, --workspace-token, --daemon.
• tb local stop
• tb local restart
• Options: --use-aws-creds, --volumes-path, --skip-new-version, --yes.
• tb local status
• tb local remove
• tb local version
• tb local generate-tokens

Notes:

• If you remove the container without a persisted volume, local data is lost.
• Manual flags (--local, --cloud, --branch) still work as overrides.

Local-First Workflow

1) tb local start 2) Set dev_mode to local in tinybird.config.json 3) Run tb dev in a new terminal — watches for file changes and auto-rebuilds 4) Test endpoints/queries locally with tb endpoint data <pipe_name> 5) Run tb deploy only when user explicitly requests production deployment

Use --volumes-path to persist data between restarts.

tb dev is the recommended development command. It watches your project files and automatically rebuilds Data Sources and Endpoints when changes are detected.

Connecting to the Tinybird UI

• tb dev --ui: Builds in watch mode and connects the local project to the Tinybird UI for visual exploration and debugging.
• tb open: Opens the workspace in the browser.

These are useful for visually inspecting query results, exploring Data Source schemas, or debugging pipe logic.

Troubleshooting

• If status shows unhealthy, run tb local restart and re-check.
• If authentication is not ready, wait or restart the container.
• If memory warnings appear in status, increase Docker memory allocation.
• If Local is not running, start it with tb local start.

Mock Data Generation

Tinybird mock data flow (as implemented by the agent) for a datasource:

1) Build a SQL query that returns mock rows. 2) Execute locally with a limit and format using tb --output=json|csv '<sql>' --rows-limit <rows> command. 3) Preview the generated output. 4) Confirm creation of a fixture file under fixtures/. 5) Write the fixture file:

• fixtures/<datasource_name>.ndjson or fixtures/<datasource_name>.csv

6) Confirm append. 7) Append the fixture to the datasource in Tinybird Local.

Example Mock Query

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)

Notes:

• The query must return exactly ROWS rows via FROM numbers(ROWS).
• Do not add FORMAT or a trailing semicolon in the mock query itself.

Error Handling Notes

• If the datasource is in quarantine, query <datasource_name>_quarantine and surface the first 5 rows.
• If append fails with "must be created first with 'mode=create'", rebuild the project and retry.

Secrets

Usage in Files

• Secret syntax: {{ tb_secret("SECRET_NAME", "DEFAULT_VALUE_OPTIONAL") }}.
• Use secrets for credentials in connections and pipe SQL.
• Secrets in pipe files do not allow default values.
• Secrets in connection files may include default values.
• Do not replace secrets with dynamic parameters when secrets are required.

CLI: tb secret

• List secrets:
• tb secret ls
• tb secret ls --match _test

• Set or update a secret:
• tb secret set SECRET_NAME SECRET_VALUE
• tb secret set SECRET_NAME (prompts securely)
• tb secret set SECRET_NAME --multiline (opens editor)

• Remove a secret:
• tb secret rm SECRET_NAME

Local Secrets

• If a .env.local file is present, its secrets are loaded automatically in Tinybird Local.

Tokens

• Resource-scoped tokens are defined in datafiles.
• Tinybird tracks and updates resource-scoped tokens from datafile contents.

Scopes and usage:

• DATASOURCES:READ:datasource_name => TOKEN <token_name> READ in .datasource files
• DATASOURCES:APPEND:datasource_name => TOKEN <token_name> APPEND in .datasource files
• PIPES:READ:pipe_name => TOKEN <token_name> READ in .pipe files

Examples:

TOKEN app_read READ
TOKEN landing_append APPEND

For operational tokens (not tied to resources):

tb token create static new_admin_token --scope <scope>

Scopes: TOKENS, ADMIN, ORG_DATASOURCES:READ, WORKSPACE:READ_ALL.

JWT Tokens

JWT tokens have a TTL and can only use PIPES:READ or DATASOURCES:READ scopes. They are intended for end users calling endpoints or reading datasources without exposing a master API key.

Create a JWT token:

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

Datasource read with filter:

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

Multiple scopes and resources (counts must match), with optional fixed params for 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'"