@brightsy/cli

Unified Brightsy Command Line Interface for chatting with agents, building component libraries, and deploying to Brightsy sites.

Installation

npm install -g @brightsy/cli

Authentication

# Login with OAuth
brightsy login

# Check current account
brightsy whoami

# Logout
brightsy logout

Chat with Agents

# Chat with an agent (will prompt to select one)
brightsy chat "Hello, how are you?"

# Chat with a specific agent
brightsy chat --agent <agent-id> "Help me with my project"

# List available agents
brightsy agents

# Reset chat history
brightsy chat --reset

Component Libraries

Create a New Library

# Scaffold a new component library
brightsy create my-components

# Or create an app
brightsy create my-app --template app

Connect to Brightsy

# Connect your project to a site and library
brightsy connect

Push to Environment

# Push to an environment (interactive)
brightsy push

# Push to specific environment
brightsy push --env production

# Register local dev server
brightsy push --dev
brightsy push --dev --port 3000

Check Status

# Show connection and environment status
brightsy status

Configuration Files

Global Config (~/.brightsy/config.json)

Stores authentication tokens and account information.

Project Config (.brightsy.json)

Stores site and library connection for the current project:

{
  "siteId": "uuid",
  "siteName": "My Site",
  "libraryId": "uuid",
  "libraryName": "my-components",
  "defaultEnv": "development"
}

Git Branch to Environment Mapping

When pushing, the CLI suggests environments based on your git branch:

• main, master, production, prod → production
• dev, develop, development → development
• Other branches → use branch name as environment

Development & Testing

Building Locally

cd packages/brightsy-cli
pnpm build

Manual Testing

Run the CLI directly after building:

node dist/index.js --help
node dist/index.js whoami
node dist/index.js status

Or link globally for testing:

pnpm link --global
brightsy --help

Running Tests

# Run unit and integration tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run API mocking tests (uses MSW)
pnpm test:api

Test Structure

src/
  config.test.ts          # Config utility tests
  git.test.ts             # Git utility tests (getEnvironmentFromBranch, etc.)
  oauth.test.ts           # OAuth/PKCE tests
  templates.test.ts       # Template generation tests
  cli.integration.test.ts # CLI command integration tests
  api.test.ts             # API mocking tests with MSW
  test/
    mocks/
      handlers.ts         # MSW request handlers
      server.ts           # MSW server setup
      index.ts            # Mock exports

Testing Checklist

When making changes, verify:

| Command | What to verify | |---------|----------------| | brightsy login | Opens browser, OAuth flow works, config saved to ~/.brightsy/config.json | | brightsy logout | Removes config file | | brightsy whoami | Shows logged-in account or "Not logged in" | | brightsy chat "hello" | Agent/model selection, streaming response | | brightsy agents | Lists available agents | | brightsy models | Lists available models | | brightsy create my-lib | Scaffolds correct file structure | | brightsy connect | Interactive site/library selection | | brightsy push --dev | Registers local dev server | | brightsy status | Shows connection info |

License

MIT