@butterbase/cli

Command-line tool for Butterbase project scaffolding and backend management.

Installation

npm install -g @butterbase/cli

Quick Start

# Login with your API key
butterbase login

# Create a new app
butterbase apps create my-app

# Set as current app
butterbase apps use app_abc123

# Get current schema
butterbase schema get --output schema.json

# Apply schema changes
butterbase schema apply schema.json

# Deploy a function
butterbase functions deploy ./functions/hello.ts

# Upload a file
butterbase storage upload ./image.png

Commands

Authentication

# Login
butterbase login

# Logout
butterbase logout

Configuration

# Show current config
butterbase config get

# Set endpoint
butterbase config set endpoint https://api.butterbase.ai

# Set API key
butterbase config set apiKey bb_key_...

Configuration is stored in ~/.butterbase/config.json.

Apps

# List all apps
butterbase apps list

# Create new app
butterbase apps create my-app

# Set current app (used by other commands)
butterbase apps use app_abc123

# Delete app
butterbase apps delete app_abc123

Schema

# Get current schema
butterbase schema get

# Save schema to file
butterbase schema get --output schema.json

# Preview schema changes (dry-run)
butterbase schema apply schema.json --dry-run

# Apply schema changes
butterbase schema apply schema.json

# Apply with custom migration name
butterbase schema apply schema.json --name "add_users_table"

# Use specific app
butterbase schema get --app app_abc123

Functions

# List deployed functions
butterbase functions list

# Deploy function
butterbase functions deploy ./functions/hello.ts

# Deploy with custom name
butterbase functions deploy ./functions/hello.ts --name my-function

# Deploy with description
butterbase functions deploy ./functions/hello.ts --description "Hello world function"

# Deploy cron function
butterbase functions deploy ./functions/cleanup.ts --trigger cron

# View function logs
butterbase functions logs my-function

# View error logs only
butterbase functions logs my-function --level error

# Limit number of logs
butterbase functions logs my-function --limit 50

Storage

# List storage objects
butterbase storage list

# Upload file
butterbase storage upload ./image.png

# Delete object
butterbase storage delete obj_abc123

Global Options

Most commands support the --app flag to specify an app ID:

butterbase schema get --app app_abc123
butterbase functions list --app app_abc123
butterbase storage list --app app_abc123

If --app is not provided, the CLI uses the current app set with butterbase apps use.

Configuration

The CLI stores configuration in two places:

1. Global config: ~/.butterbase/config.json

   • API key
   • Default endpoint
   • Current app

2. Project config: .butterbase/config.json (in project directory)

   • App ID
   • Endpoint override

Project config takes precedence over global config.

Environment Variables

You can also configure the CLI using environment variables:

• BUTTERBASE_API_KEY - API key
• BUTTERBASE_ENDPOINT - API endpoint URL

Examples

Complete Workflow

# 1. Login
butterbase login

# 2. Create app
butterbase apps create my-grocery-app

# 3. Set as current
butterbase apps use app_abc123

# 4. Create schema file
cat > schema.json <<EOF
{
  "tables": {
    "grocery_items": {
      "columns": {
        "id": { "type": "uuid", "primaryKey": true, "default": "gen_random_uuid()" },
        "name": { "type": "text" },
        "quantity": { "type": "integer", "default": "1" },
        "purchased": { "type": "boolean", "default": "false" },
        "user_id": { "type": "uuid" },
        "created_at": { "type": "timestamptz", "default": "now()" }
      }
    }
  }
}
EOF

# 5. Apply schema
butterbase schema apply schema.json

# 6. Deploy function
butterbase functions deploy ./functions/add-item.ts

# 7. Upload image
butterbase storage upload ./logo.png

Working with Multiple Apps

# Create production app
butterbase apps create my-app-prod
# Returns: app_prod123

# Create staging app
butterbase apps create my-app-staging
# Returns: app_staging456

# Deploy to production
butterbase functions deploy ./functions/api.ts --app app_prod123

# Deploy to staging
butterbase functions deploy ./functions/api.ts --app app_staging456

# Switch between apps
butterbase apps use app_prod123
butterbase apps use app_staging456

Development

# Install dependencies
npm install

# Build
npm run build

# Test locally
node dist/bin/butterbase.js --help

Integrations

# List available integrations (curated)
butterbase integrations list --app app_abc123

# Search the full catalog
butterbase integrations list --search salesforce --app app_abc123

# Show configured integrations
butterbase integrations config --app app_abc123

# Enable a toolkit
butterbase integrations configure gmail --app app_abc123

# Disable a toolkit
butterbase integrations disable gmail --app app_abc123

# Generate OAuth URL for an end-user
butterbase integrations connect gmail --redirect-url https://yourapp.com/settings --app app_abc123

# List connected accounts
butterbase integrations connections --app app_abc123

# Disconnect an account
butterbase integrations disconnect <connection-id> --app app_abc123

# List tools for a toolkit
butterbase integrations tools gmail --app app_abc123

# Execute a tool
butterbase integrations execute GMAIL_SEND_EMAIL --data '{"to":"[email protected]","subject":"Hi","body":"Hello"}' --app app_abc123

License

MIT