Tambo Docs

Step-by-step Tambo CLI workflows for new projects, existing React apps, component management, and ongoing maintenance.

This guide covers the most common workflows you'll use with the Tambo CLI, organized by scenario and use case.

Getting Started Workflows

New Project Setup

For brand new projects, use the template approach:

# Create new project with template
npm create tambo-app@latest my-tambo-app
cd my-tambo-app

# Complete setup with API key
npx tambo init

# Start development
npm run dev

Adding to Existing Project

For existing React/Next.js projects:

# Quick setup with components
npx tambo full-send

# Or step-by-step approach
npx tambo init
npx tambo add message-thread-full

API Key Required

After running init or full-send, make sure to add your API key to .env.local: NEXT_PUBLIC_TAMBO_API_KEY=your_api_key_here

Component Management Workflows

Adding Components Strategically

Start with core components, then add specialized ones:

# 1. Start with a message interface
npx tambo add message-thread-collapsible

# 2. Add form capabilities
npx tambo add form

# 3. Add visualization components
npx tambo add graph canvas-space

# 4. Add advanced interactions
npx tambo add control-bar

Checking What's Installed

# See what components you have
npx tambo list

# Check if updates are available
npx tambo update --dry-run

Development Workflows

Building a Chat Interface

# 1. Setup project
npx tambo init

# 2. Add chat component
npx tambo add message-thread-full

# 3. Configure in your app
# Add TamboProvider to layout.tsx
# Import and use MessageThreadFull component

Building a Form Experience

# 1. Add form components
npx tambo add form input-fields

# 2. Register form-related tools in lib/tambo.ts
# 3. Create form validation components

Building a Data Visualization App

# 1. Add visualization components
npx tambo add graph canvas-space

# 2. Add control interface
npx tambo add control-bar

# 3. Register data tools for fetching/processing

Maintenance Workflows

Keeping Everything Updated

# Option 1: Update everything at once
npx tambo upgrade

# Option 2: Update selectively
npx tambo update installed  # All components
npx tambo update form graph # Specific components

Migrating from Legacy Structure

If you installed Tambo components before the directory structure change (more info here):

# 1. Check what needs migration
npx tambo migrate --dry-run

# 2. Perform migration
npx tambo migrate

# 3. Test everything still works
npm run dev

Troubleshooting Workflows

Dependency Conflicts

If you encounter peer dependency issues:

# Use legacy peer deps flag
npx tambo add message-thread-full --legacy-peer-deps
npx tambo upgrade --legacy-peer-deps

Component Not Working

# 1. Check if component is properly installed
npx tambo list

# 2. Update to latest version
npx tambo update <component-name>

# 3. Check your TamboProvider setup
# Make sure API key is set
# Verify component is imported correctly

Clean Reinstall

# 1. Remove existing components
rm -rf components/tambo/*

# 2. Reinstall fresh
npx tambo add message-thread-full form graph

# 3. Update configuration
npx tambo upgrade

CI/CD Workflows

The Tambo CLI automatically detects non-interactive environments (CI/CD, piped input/output) and provides helpful guidance. Use these patterns for automated pipelines.

GitHub Actions Setup

name: Setup Tambo

on:
  push:
    branches: [main]

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Install dependencies
        run: npm ci

      - name: Initialize Tambo
        run: npx tambo init --api-key="${{ secrets.TAMBO_API_KEY }}"

      - name: Add components
        run: npx tambo add message-thread-full form --yes

Docker Build

# Pass API key as build argument
ARG TAMBO_API_KEY

RUN npx tambo init --api-key="$TAMBO_API_KEY"
RUN npx tambo add message-thread-full --yes

Build with:

docker build --build-arg TAMBO_API_KEY="$TAMBO_API_KEY" .

Non-Interactive Flags

In CI/CD, always provide these flags to avoid prompts:

# Initialize with direct API key
npx tambo init --api-key="$TAMBO_API_KEY"

# Add components without prompts
npx tambo add form graph --yes --prefix=src/components/tambo

# Upgrade without prompts (required in CI)
npx tambo upgrade --yes

Handling Exit Codes

The CLI uses exit code 2 when user action is required:

npx tambo init --api-key="$TAMBO_API_KEY"
status=$?
if [ $status -eq 2 ]; then
  echo "Missing required arguments"
  exit 1
elif [ $status -ne 0 ]; then
  echo "Command failed"
  exit 1
fi

For more details on non-interactive mode and exit codes, see Global Options.

Quick Reference

Most Common Commands

# Quick setup
npx tambo full-send

# Add components
npx tambo add message-thread-full form

# Update everything
npx tambo upgrade

# Check status
npx tambo list

Flags You'll Use Often

For detailed information about all available flags and options, see the Global Options page.

Quick reference:

--yes - Skip confirmation prompts
--legacy-peer-deps - Fix dependency conflicts
--prefix=<path> - Custom component directory
--dry-run - Preview changes before applying

Common Workflows