Brightsy CLI

Sites & Page Building

# List all sites
brightsy sites list

# Get site details
brightsy sites get site-uuid

# Create new site
brightsy sites create "My Website" --domain my-site.com

# Update site
brightsy sites update site-uuid --name "Updated Name"

# Delete site
brightsy sites delete site-uuid --confirm

Component Library Development

Create New Library

# Scaffold a new component library
brightsy create my-components

# Create an app-style library
brightsy create my-dashboard --template app

Connect to Brightsy

cd my-components
# Interactive site/library selection
brightsy connect

Development & Deployment

# Start local development server
npm run dev

# Register local dev server with Brightsy
brightsy push --dev

# Build and deploy to production
npm run build
brightsy push

# Deploy to specific environment
brightsy push --env staging

Check Status

# Show connection and deployment status
brightsy status

Automation & Integration

Scenarios (Workflows)

# List automation scenarios
brightsy scenarios list

# Create new scenario
brightsy scenarios create "Welcome Email" --trigger-type record_create

# Trigger scenario manually
brightsy scenarios trigger scenario-uuid --data '{"userId":"123"}'

Schedules

# List scheduled tasks
brightsy schedules list

# Create daily schedule
brightsy schedules create "Daily Report" --cron "0 9 * * *" --scenario-id scenario-uuid

Webhooks

# List webhooks
brightsy webhooks list

# Create webhook
brightsy webhooks create "Slack Notifications" "https://hooks.slack.com/..." --events "record.created,record.updated"

API Keys & Security

# List API keys
brightsy apikeys list

# Create new API key
brightsy apikeys create "Frontend Key" --permissions '{"cms":{"blog-post":{"read":true,"write":false}}}'

# Delete API key
brightsy apikeys delete key-uuid

File Management

# List files in a folder
brightsy files list --path "documents"

# Upload a file
brightsy files upload image.jpg --folder "images"

# Delete a file
brightsy files delete "old-file.pdf"

Advanced Usage

Custom Endpoints

All commands support custom API endpoints:

brightsy login --endpoint https://my-custom.brightsy.ai
brightsy chat --endpoint https://staging.brightsy.ai "Test message"

Scripting & Automation

The CLI is designed for scripting. All commands return appropriate exit codes:

#!/bin/bash
# Deploy script example
npm run build
brightsy push --env production
if [ $? -eq 0 ]; then
  echo "Deployment successful"
else
  echo "Deployment failed"
  exit 1
fi

Git Integration

The CLI automatically detects Git branches for environment selection:

• main/master → production
• dev/develop → development
• Other branches → branch name

MCP Integration

The Brightsy CLI is fully compatible with Model Context Protocol (MCP) servers. For detailed MCP setup, see the MCP documentation.

The CLI and MCP servers share the same authentication, so you can use them interchangeably.

SDK Integration

The CLI works seamlessly with the BrightsyClient SDK:

import { BrightsyClient } from '@brightsy/client';

const client = new BrightsyClient({
  // CLI authentication can be used programmatically
  // by reading the same config files
});

Troubleshooting

Authentication Issues

Problem: "Not logged in" error

Solution:

brightsy login

Problem: Token expired

Solution: The CLI automatically refreshes tokens. If issues persist:

brightsy logout
brightsy login

Connection Issues

Problem: Network connectivity errors

Solutions:

• Check internet connection
• Verify firewall settings allow HTTPS
• Try custom endpoint if using on-premise deployment

Command Not Found

Problem: brightsy: command not found

Solutions:

• Install globally: npm install -g @brightsy/cli
• Use npx: npx @brightsy/cli
• Check Node.js version (18+ required)

Permission Errors

Problem: Access denied to resources

Solutions:

• Verify account has access to requested resources
• Check OAuth scopes include required permissions
• Contact account administrator for access

Build/Deploy Issues

Problem: Component library deployment fails

Solutions:

• Ensure project is connected: brightsy status
• Check build process completes successfully
• Verify library has valid component exports
• Check Brightsy account has library creation permissions

Configuration Files

The CLI stores configuration in your home directory:

• Auth Config: ~/.brightsy/config.json - OAuth tokens and account info
• Project Config: .brightsy.json - Site/library connections per project

Best Practices

• Keep Authentication Fresh: Use brightsy login when tokens expire
• Use Descriptive Names: Name resources clearly for CLI discoverability
• Version Control: Include .brightsy.json in version control for team sharing
• Environment Separation: Use different accounts for development/production
• Regular Updates: Keep CLI updated with npm update -g @brightsy/cli
• Script Integration: Use CLI commands in CI/CD pipelines for automation
• Error Handling: Always check exit codes in scripts
• Resource Limits: Be mindful of API rate limits (100 req/min, 1000 req/hour)