Brightsy CLI

The Brightsy Command Line Interface (CLI) is a comprehensive tool for interacting with Brightsy AI, managing content, building component libraries, and integrating with development workflows. It features OAuth 2.1 authentication with automatic token refresh and supports the full Brightsy platform API.

Installation

Install the Brightsy CLI globally using npm:

npm install -g @brightsy/cli

Or run it directly with npx:

npx @brightsy/cli

Authentication

The CLI uses OAuth 2.1 with PKCE (Proof Key for Code Exchange) for secure authentication. No manual API keys required.

Login

brightsy login

This opens your browser for authentication and stores tokens locally. The CLI automatically refreshes tokens when they expire.

Account Information

brightsy whoami

Shows your current account and authentication status.

Logout

brightsy logout

Clears stored authentication tokens.

Chat & AI Interaction

Interactive Chat

Start an interactive chat session with AI agents or models:

brightsy chat

The CLI will prompt you to choose between:

• Agent Chat: Use configured agents with tools and memory
• Direct Model: Chat directly with AI models for simple completions

Direct Chat Commands

# Chat with a message
brightsy chat "Help me debug this React component"

# Chat with a specific agent
brightsy chat --agent <agent-id> "Analyze this code"

# Direct model completion
brightsy chat --model claude_sonnet_4_5 "Explain this algorithm"

# Start a new conversation
brightsy chat --new "Fresh conversation topic"

List Available Resources

# List your configured agents
brightsy agents

# List available AI models for direct completion
brightsy models

Content Management (CMS)

Records Management

# List records of a type
brightsy records list blog-post --limit 10 --status published

# Get a specific record
brightsy records get blog-post abc123

# Create a new record
brightsy records create blog-post --data '{"title":"New Post","content":"Content here"}'

# Update a record
brightsy records update blog-post abc123 --data '{"title":"Updated Title"}'

# Delete a record
brightsy records delete blog-post abc123

Record Types (Schemas)

# List all record types
brightsy record-types list --search blog

# Get record type schema
brightsy record-types get blog-post

# Create new record type
brightsy record-types create "Product" --slug product --schema '{"type":"object","properties":{"name":{"type":"string"}}}'

# Update record type
brightsy record-types update product --name "Updated Product"

# Delete record type (with confirmation)
brightsy record-types delete product --confirm

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)