# Common Workflows
URL: /reference/cli/workflows

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:

```bash
# 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:

```bash
# Quick setup with components
npx tambo full-send

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

<Callout type="info" title="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`
</Callout>

## Component Management Workflows

### Adding Components Strategically

Start with core components, then add specialized ones:

```bash
# 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

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

### Checking What's Installed

```bash
# See what components you have
npx tambo list

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

## Development Workflows

### Building a Chat Interface

```bash
# 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

```bash
# 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

```bash
# 1. Add visualization components
npx tambo add graph

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

# 3. Register data tools for fetching/processing
```

## Maintenance Workflows

### Keeping Everything Updated

```bash
# 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](/reference/cli/commands/migrate)):

```bash
# 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:

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

### Component Not Working

```bash
# 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

```bash
# 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

```yaml
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

```dockerfile
# 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:

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

### Non-Interactive Flags

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

```bash
# 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:

```bash
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](/reference/cli/global-options#non-interactive-mode).

## Quick Reference

### Most Common Commands

```bash
# 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](/reference/cli/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