Skip to main content
The Tinybird TypeScript SDK provides a powerful CLI for managing your data infrastructure. All commands automatically load configuration from tinybird.config.json and environment variables from .env.local.

​
Quick Reference

Init

Initialize a new Tinybird TypeScript project

Dev

Watch for changes and auto-sync with Tinybird

Build

Build and push to a Tinybird branch

Deploy

Deploy resources to production

Migrate

Migrate datafiles to TypeScript

Pull

Download cloud resources as datafiles

Login

Authenticate with Tinybird

Branch

Manage Tinybird branches

Info

Display project and workspace information

​
Development Workflow

Typical development workflow using CLI commands:
  1. Initialize your project with tinybird init
  2. Develop with auto-sync using tinybird dev
  3. Build to test changes on a branch with tinybird build
  4. Deploy to production with tinybird deploy

​
Branch vs Deploy

The SDK enforces safe deployment practices:
  • dev and build: Only work on feature branches (not main)
  • deploy: Only deploys to production from main branch
This prevents accidental production deployments during development.

​
Development Modes

The CLI supports two development modes:

​
Branch Mode (Default)

Uses Tinybird Cloud with git-based branching:
tinybird.config.json
{
  "devMode": "branch"
}
  • Creates Tinybird branches automatically from git branches
  • Each branch gets isolated workspace
  • Perfect for team collaboration

​
Local Mode

Runs against a local Tinybird container:
tinybird.config.json
{
  "devMode": "local"
}
  • Works offline without cloud authentication
  • Faster iteration during development
  • Requires local Docker container

​
Command Categories

​
Project Setup

  • init: Bootstrap a new project
  • login: Authenticate with Tinybird

​
Development

  • dev: Watch mode with auto-sync
  • build: Build to feature branch
  • deploy: Deploy to production

​
Resource Management

  • pull: Download cloud resources
  • migrate: Convert datafiles to TypeScript
  • branch: Manage branches
  • info: View project status

​
Environment Variables

All commands read from:
  • .env.local (recommended for local development)
  • .env (fallback)
  • process.env (system environment)
Required variables:
.env.local
TINYBIRD_TOKEN=p.your_token_here

​
Global Flags

Most commands support:
  • --help: Show command help
  • --cwd <path>: Run from specific directory

​
Exit Codes

CLI commands follow standard exit codes:
  • 0: Success
  • 1: Error (build failed, authentication failed, etc.)
  • 130: User cancelled (SIGINT)

​
Configuration

All commands respect settings in tinybird.config.json: 
{
  "include": ["src/tinybird.ts"],
  "token": "${TINYBIRD_TOKEN}",
  "baseUrl": "https://api.tinybird.co",
  "devMode": "branch"
}
See individual command pages for detailed usage and examples.

Build docs developers (and LLMs) love

Get started for freeTalk to us