---
title: "CLI 4.0: A better workflow for agents and humans"
excerpt: "Configure dev_mode once and tb build and tb deploy just work. No more --cloud, --branch, or --local flags. Plus SDK bridges and zero AI dependencies."
authors: "Rafa Moreno"
categories: "Product updates"
createdOn: "2026-03-09 00:00:00"
publishedOn: "2026-03-09 12:00:00"
status: "published"
---

We rethought the CLI with two goals: make it easy for coding agents to drive, and take full advantage of Tinybird's [data branching](https://www.tinybird.co/docs/forward/test-and-deploy/branches) capabilities.

That meant simplifying. The usual flow needed too many flags. Every `tb build` or `tb deploy` needed you to specify `--cloud`, `--local`, or `--branch`. If you forgot, you'd deploy to the wrong place. If you switched contexts, you'd have to remember which flag to pass. Even us internally were confused sometimes.

CLI 4.0 fixes this. Configure your environment once, and `tb build` and `tb deploy` just work.

```bash
tb init          # scaffold your project and dev env (branch or local)
# create your .datasource, .pipe files or TypeScript SDK resources
tb build         # builds against your configured environment
tb deploy        # deploys to production
```

That's the whole workflow.

## One config, no flags

The CLI now reads a `dev_mode` setting from your `tinybird.config.json` file:

```json
{
  "type": "cli",
  "dev_mode": "branch",
  "folder": "tinybird"
}
```

Three modes:

**`local`.** `tb build` runs against Tinybird Local. `tb deploy` routes to Cloud production.

```bash
$ tb build
Using dev_mode=local. Running build against Tinybird Local.

$ tb deploy
Using dev_mode=local. Running deploy against Tinybird Cloud main.
```

**`branch`.** `tb build` reads your git branch, sanitizes the name (`feature/new-ui` becomes `feature_new_ui`), and targets that Tinybird branch. Creates it if it doesn't exist. `tb deploy` routes to Cloud production. Every git branch gets its own isolated Tinybird environment automatically. No manual branch creation, no flag to remember.

```bash
$ git checkout -b feature/new-ui
$ tb build
Using dev_mode=branch. Running build against Tinybird branch 'feature_new_ui'.
```

There's a safety check: if you're on `main` or `master`, `tb build` in branch mode refuses to run and tells you to use `tb deploy` instead.

**`manual`.** Same as before, with CLI 3.X. You pass `--cloud`, `--local`, or `--branch` explicitly. This is the default for backwards compatibility.

Explicit flags always win. If you pass `--branch my_branch`, dev_mode is ignored.

## Clear command boundaries

Each environment now has its own top-level command:

| Command | Environment |
| --- | --- |
| `tb workspace` | Cloud production |
| `tb branch` | Branches |
| `tb local` | Tinybird Local |

No ambiguity about where you're operating. `tb branch clear` resets your branch. `tb local clear` resets your local workspace. `tb workspace` manages your cloud state.

## Works with all project types

The CLI auto-detects your project type and handles it transparently:

**Datafiles** (`.datasource`, `.pipe`). The classic Tinybird format. Works exactly as before.

**TypeScript SDK.** If your project has a `tinybird.config.mjs` or `tinybird.config.json`, the CLI generates datafiles from your TypeScript definitions before running `build`, `deploy`, or `preview`. No separate build step needed.

```bash
# All project types work the same way:
tb build    # detects project type, generates if needed, builds
tb deploy   # detects project type, generates if needed, deploys
tb preview  # detects project type, generates if needed, previews
```

You pick the language. The CLI handles the rest.

## A simpler CLI, the smart part is in the agent

A few weeks ago we [sunset Tinybird Code](https://www.tinybird.co/blog-posts/deprecating-tinybird-code), our embedded AI agent. CLI 4.0 completes that transition.

The entire agent module is gone. 20+ files, ~5,500 lines of code, four AI dependencies (`anthropic`, `pydantic-ai-slim`, `llm`, `plotext`). The install is lighter (no AI packages to download), startup is faster (no heavy imports on cold start), and there are no more transitive dependency conflicts.

Removed commands:

| Command | What happened |
| --- | --- |
| `tb` (no subcommand) | Was agent mode. Now shows `--help`. |
| `tb --prompt "..."` | Removed. |
| `tb mock` | Removed. Use `fixtures/` folder + agent skills. |
| `tb test create` | Removed. |
| `tb create` | Renamed to `tb init`. `tb create` still works with a deprecation warning. |

The AI-assisted commands are gone because they're no longer needed. Your coding agent (Claude Code, Cursor, Codex) does what `--prompt` used to do, with full context of your codebase, and without being embedded in the CLI. The CLI gives agents what they need: structured output, explicit error messages, and [agent skills](https://www.tinybird.co/docs/forward/get-started/quick-start-coding-agents) for Tinybird-specific knowledge.

Interactive shell from `tb dev` is also gone. Coding agents were not able to write there. Instead, we log what's happening, as `npm run dev` does.

```bash
➜ cli4 git:(new_feature) » tb dev
Running against Tinybird Local
» Building project...
No changes. Build skipped.

Watching for changes...


⟲ Changes detected in new_ds.datasource

» Rebuilding project...
✓ datasources/new_ds.datasource created
------------

✓ Rebuild completed in 0.5s
```

## What didn't change

Your `.datasource` and `.pipe` files work exactly as before. Authentication, data ingestion, endpoint queries, branch management. All unchanged.

If you weren't using `tb mock`, `--prompt`, or the interactive agent, upgrading is a no-op.

## Upgrade

```bash
tb update
```

Make sure to update your Tinybird agent skills too:

```bash
npx skills add @tinybirdco/tinybird-agent-skills
```

or, if already installed:

```bash
npx skills update
```

PS: If you need help migrating from Classic to Forward, [get in touch with support](https://www.tinybird.co/docs/support).

{% cta
  title="Try CLI 4.0"
  text="Configure dev_mode, drop the flags. tb build and tb deploy just work."
  button={href: "https://www.tinybird.co/docs/forward/get-started/quick-start", target: "_blank", text: "Get started"}
/%}