Tinybird CLI Guidelines

What Is This?

Overview

The Tinybird CLI, invoked through the tb command, is the primary tool for interacting with Tinybird workspaces, managing local development environments, deploying data projects, and performing data operations. It provides a command-line interface that connects your local development workflow to Tinybird's real-time analytics backend, allowing developers to build, test, and ship data pipelines without leaving the terminal.

The CLI supports a full development lifecycle, from initializing a local project and iterating on pipe transformations to deploying production-ready endpoints and managing data sources. It integrates with Tinybird Local, a local emulation environment that lets you validate your project before pushing changes to a remote workspace. This makes it possible to catch configuration errors and logic issues early in the development process.

Whether you are appending new data, replacing existing data sources, or orchestrating complex deployment workflows, the tb command provides consistent, scriptable operations that fit naturally into CI/CD pipelines and automated workflows.

Who Should Use This

• Data engineers building and maintaining real-time analytics pipelines on Tinybird
• Backend developers integrating Tinybird API endpoints into application workflows
• DevOps engineers automating Tinybird deployments through CI/CD systems
• Analytics engineers iterating on SQL transformations and materialized views locally
• Platform teams managing multiple Tinybird workspaces across environments
• Technical leads reviewing and standardizing data project structures and deployment practices

Why Use It?

Problems It Solves

• Manual workspace management through the Tinybird UI does not scale for teams working across multiple environments or deploying frequently
• Without a local development environment, testing changes requires pushing directly to a shared workspace, which risks breaking production endpoints
• Coordinating data ingestion, transformation, and deployment steps manually introduces errors and inconsistency
• Reproducing workspace configurations across staging and production environments is difficult without version-controlled, CLI-driven workflows
• Debugging data pipeline issues is slower when developers cannot inspect and iterate locally before deploying

Core Highlights

• Full project lifecycle management from initialization to deployment
• Local development support through Tinybird Local for offline iteration
• Data source operations including append, replace, and delete
• Pipe and endpoint management with version-controlled .pipe and .datasource files
• Workspace authentication and multi-workspace support
• Scriptable commands suitable for CI/CD integration
• Consistent behavior across local and remote environments
• Detailed output and error reporting for debugging

How to Use It?

Basic Usage

Authenticate and connect to a workspace using your Tinybird token:

tb auth --token <your_token>

Initialize a new project in the current directory:

tb init

Start a local Tinybird development server:

tb local start

Push your local project to the connected workspace:

tb push

Specific Scenarios

Appending data to a data source:

tb datasource append my_datasource data.ndjson

This command adds new rows to an existing data source without removing existing data, which is useful for incremental ingestion workflows.

Deploying with validation:

tb push --force --populate

The --populate flag triggers materialized views to rebuild after deployment, ensuring downstream pipes reflect the latest data source state.

Real-World Examples

A CI/CD pipeline step that authenticates and deploys on every merge to main:

tb auth --token $TINYBIRD_TOKEN
tb push --force

Running a local test cycle before pushing changes:

tb local start
tb push --local
tb pipe data my_pipe --local
tb local stop

When to Use It?

Use Cases

• Setting up a new Tinybird project from scratch in a version-controlled repository
• Running local development iterations without affecting shared workspaces
• Deploying data pipeline changes through automated CI/CD workflows
• Ingesting batch data files into existing data sources
• Inspecting pipe output and endpoint responses during debugging
• Managing authentication across multiple workspaces or environments
• Rebuilding materialized views after schema or logic changes

Important Notes

Requirements

• A valid Tinybird account and workspace token are required for remote operations
• The tb CLI must be installed and available in the system path
• Tinybird Local requires Docker to be running for local environment support

Usage Recommendations

Do:

• Store tokens in environment variables or secret managers, not in source code
• Run tb diff before every push to review pending changes
• Use Tinybird Local to validate changes before deploying to production
• Keep .datasource and .pipe files under version control
• Test endpoint responses with tb pipe data before releasing

Do not:

• Push directly to production workspaces without testing locally first
• Share workspace tokens in logs, repositories, or chat messages
• Skip the --populate flag when deploying changes that affect materialized views
• Run destructive data operations without confirming the target workspace