@butterbase/cli

@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:

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

  • API key
  • Default endpoint
  • Current app

• 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

License

MIT