Ensemble CLI - Ensemble Edge

Overview

The Ensemble CLI is the unified command-line interface for the entire Ensemble ecosystem. Instead of installing and managing separate CLIs for each tool, you get a single entry point that orchestrates everything.

# One command to get started - no installation needed
npx @ensemble-edge/ensemble

# Or run specific commands directly
npx @ensemble-edge/ensemble conductor init my-project   # Create Conductor projects
npx @ensemble-edge/ensemble edgit tag create v1.0.0     # Version components

Why a Unified CLI?

The Ensemble CLI provides a single interface for all tools in the ecosystem:

# No installation needed - just run with npx
npx @ensemble-edge/ensemble

# Or run specific commands directly
npx @ensemble-edge/ensemble conductor init my-project
npx @ensemble-edge/ensemble edgit tag create prompt v1.0.0

Benefits:

Single installation - One package to install and update
Consistent interface - Same patterns across all tools
Automatic discovery - CLI suggests related tools as you work
Simplified CI/CD - One binary in your pipelines

Quick Start

Getting Started

# Launch the interactive wizard (recommended)
npx @ensemble-edge/ensemble

# Or run a specific command
npx @ensemble-edge/ensemble conductor init my-project
npx @ensemble-edge/ensemble --help

Verify It Works

npx @ensemble-edge/ensemble --version
# Output: ensemble v0.1.4

npx @ensemble-edge/ensemble --help
# Shows all available commands

Checking for Updates (Landscape View)

The --version flag scans your directory tree and shows all discovered Ensemble projects in a tree view:

ensemble --version

Example output:

Ensemble Landscape
══════════════════════════════════════════════════════════════════

ensemble v0.1.10 (latest)

Found 3 projects:

./my-conductor-app (conductor, pnpm)
├─ @anthropic-ai/sdk 0.25.2 ✓
├─ @ensemble-edge/conductor 0.7.26 → 0.8.0 ⬆
└─ @ensemble-edge/ensemble 0.1.10 ✓

./analytics-service (conductor, npm)
├─ @anthropic-ai/sdk 0.25.2 ✓
└─ @ensemble-edge/conductor 0.7.26 → 0.8.0 ⬆

./docs-site (edgit, pnpm)
└─ @ensemble-edge/edgit 0.4.4 ✓

══════════════════════════════════════════════════════════════════
Summary: 3 projects, 2 with updates available (3 packages total)

Run 'ensemble upgrade' to update packages interactively.

The version command:

Scans your workspace - Recursively finds all Ensemble projects (up to 3 levels deep)
Tree view display - Shows each project with its packages and update status
Checks npm registry - Fetches latest versions for all packages in parallel
Detects package manager - Shows npm, pnpm, yarn, or bun per project

Upgrade Command

Manage updates across all your Ensemble projects with the interactive upgrade command:

ensemble upgrade

Features:

Multi-project scanning - Finds all Conductor and Edgit projects in your workspace
Interactive selection - Choose which projects to upgrade
Batch operations - Update multiple projects at once
Package manager aware - Uses the correct package manager per project

Example output:

Found 2 projects with updates:

  my-conductor-app (conductor)
    @ensemble-edge/conductor 0.7.26 → 0.8.0

  analytics-service (conductor)
    @ensemble-edge/conductor 0.7.26 → 0.8.0

? How would you like to proceed?
❯ Upgrade all projects (2)
  Select projects to upgrade
  Cancel

Upgrade Options

Option	Description
`--all`	Upgrade all projects without prompting
`--yes`, `-y`	Auto-confirm upgrade prompts
`--dry-run`	Show what would be upgraded without making changes
`--global`	Upgrade the globally installed ensemble CLI

Usage Examples

# Interactive upgrade (default)
ensemble upgrade

# Upgrade all projects without prompting
ensemble upgrade --all

# See what would be upgraded
ensemble upgrade --dry-run

# Upgrade the global CLI
ensemble upgrade --global

# Non-interactive upgrade for CI/CD
ensemble upgrade --all --yes

Run ensemble upgrade regularly to keep all your Ensemble projects up to date. The command is designed for managing multiple projects in a monorepo or workspace.

Command Structure

The CLI follows a simple pattern:

ensemble <tool> <command> [options]

Available Tools

Tool	Description	Example
`conductor`	Edge orchestration framework	`ensemble conductor init my-app`
`edgit`	Component versioning	`ensemble edgit tag create v1.0.0`
`cloud`	Ensemble Cloud management	`ensemble cloud deploy`
`chamber`	Secrets management	`ensemble chamber set API_KEY`
`wrangler`	Cloudflare Workers CLI (explicit passthrough)	`ensemble wrangler deploy`
`tail`	Stream live logs (shortcut for wrangler tail)	`ensemble tail`

Conductor Commands

Command	Description	Example
`conductor start`	Start dev server with smart defaults	`ensemble conductor start`
`conductor stop`	Stop development server	`ensemble conductor stop`
`conductor restart`	Restart development server	`ensemble conductor restart`
`conductor info`	Show project info	`ensemble conductor info`
`conductor init`	Create a new project	`ensemble conductor init my-app`

Global Commands

Command	Description	Example
`info`	Show project info (interactive)	`ensemble info`
`status`	Alias for info	`ensemble status`
`upgrade`	Update Ensemble packages across projects	`ensemble upgrade`
`configure`	Configure AI providers	`ensemble configure ai`

Info Command

View project information across all Ensemble products:

# Interactive product selection
ensemble info

# Or directly for a specific product
ensemble conductor info
ensemble edgit info
ensemble cloud info

# Output formats
ensemble conductor info --json      # JSON for CI/scripting
ensemble conductor info --compact   # Compact single-line format

Using ensemble info: The interactive menu lets you choose which product to view:

? Which product would you like to see info for?
❯ Conductor - AI agent orchestration
  Edgit - Git-native component versioning
  Cloud - Ensemble Cloud account

Command Naming: info is the official command. status is an alias that works identically. For Edgit specifically, ensemble edgit status passes through to git status since Edgit is git-native.

Conductor Commands

Create and manage Conductor projects:

# Initialize a new project
ensemble conductor init my-project

# With AI provider setup
ensemble conductor init my-project --provider anthropic

# Skip authentication prompts (CI/CD)
ensemble conductor init my-project --skip-auth --skip-secrets

# View project info
ensemble conductor info
ensemble conductor info --json

# Start development server (smart defaults)
ensemble conductor start
ensemble conductor start --port 3000

# Stop development server
ensemble conductor stop

# Restart development server
ensemble conductor restart

# Deploy to Cloudflare
ensemble conductor deploy

Init Options

Option	Description
`--skip-auth`	Skip Wrangler authentication check
`--skip-secrets`	Skip AI provider setup
`--provider <name>`	Pre-select AI provider (anthropic, openai, cloudflare)
`--template <name>`	Use a starter template

Start/Stop Options

The start command runs in foreground by default (you see logs in real-time):

Option	Description
`--port, -p <n>`	Server port (default: 8787, auto-finds if busy)
`--background, -b`	Run in background (detached)
`--no-auto-host`	Disable auto `--ip 0.0.0.0` in containers
`--persist-to <dir>`	Persist D1/KV data to directory

The stop command (for background servers):

Option	Description
`--force, -f`	Force stop with SIGKILL

Dev Container Support: When running in a dev container (VS Code Remote Containers, GitHub Codespaces, Docker), ensemble conductor start automatically binds to 0.0.0.0 for network access. Use --no-auto-host to disable this behavior.

Port Conflicts: If port 8787 is in use, the command automatically finds the next available port. No more “Address already in use” errors!

Edgit Commands

Version and deploy components:

# Initialize Edgit in a repo
ensemble edgit init

# View Edgit project info
ensemble edgit info
ensemble edgit info --json

# Register a component
ensemble edgit components add prompt my-prompt prompts/my-prompt.md

# Create a version tag
ensemble edgit tag create my-prompt v1.0.0

# Deploy to an environment
ensemble edgit deploy set my-prompt v1.0.0 --to prod

# List all components
ensemble edgit components list

# Git status passthrough
ensemble edgit status  # Same as 'git status'

Since Edgit is git-native, ensemble edgit status passes through to git status. Use ensemble edgit info for Edgit project information.

Cloud Commands

Manage Ensemble Cloud resources:

# Deploy to Ensemble Cloud
ensemble cloud deploy

# View Cloud account info
ensemble cloud info

# Stream logs
ensemble cloud logs --follow

Configure Command

Configure AI providers, authentication, and other settings after project creation:

# Interactive configuration menu
ensemble configure

# Configure AI provider directly
ensemble configure ai

# Pre-select a provider
ensemble configure ai --provider anthropic

# Configure Cloudflare authentication
ensemble configure auth

AI Provider Setup

The configure ai command helps you set up AI providers:

$ ensemble configure ai

? Select AI provider:
❯ Cloudflare Workers AI — Built-in, no API key needed
  Anthropic — Claude models (recommended)
  OpenAI — GPT-4 and GPT-3.5 models
  Groq — Fast inference with Llama and Mixtral

? Anthropic API key: sk-ant-...

✓ Secret stored: ANTHROPIC_API_KEY
✓ AI binding enabled in wrangler.toml

Anthropic configured!

Next steps:
  pnpm run dev

Supported Providers:

Provider	Description	API Key Required
`cloudflare`	Cloudflare Workers AI	No
`anthropic`	Claude models (recommended)	Yes
`openai`	GPT-4 and GPT-3.5 models	Yes
`groq`	Fast inference with Llama and Mixtral	Yes

Cloudflare Authentication

The configure auth command helps you log in to Cloudflare:

$ ensemble configure auth

⠋ Checking Cloudflare auth...
✓ Already logged in to Cloudflare

If not logged in, it will open a browser to complete the OAuth flow.

How It Works

The configure command:

Stores secrets securely - Uses wrangler secret put to store API keys
Updates wrangler.toml - Enables the [ai] binding automatically
Works anytime - Run after initial project creation to add AI support
Shared with init - Same wizards used during ensemble conductor init

Wrangler Commands

Use ensemble wrangler to run any Wrangler command:

# Explicit wrangler passthrough
ensemble wrangler deploy
ensemble wrangler secret put API_KEY
ensemble wrangler kv:namespace create CACHE
ensemble wrangler d1 create my-database
ensemble wrangler login
ensemble wrangler whoami

# Shortcut for streaming logs (commonly used for debugging)
ensemble tail
ensemble tail --format pretty

Why explicit wrangler? Previously, unknown commands were automatically passed to Wrangler. This caused confusing errors when you mistyped a command (e.g., ensemble start instead of ensemble conductor start). Now, Wrangler commands require the explicit ensemble wrangler prefix, and typos show helpful suggestions.

Cross-Tool Discovery

The CLI intelligently suggests related tools as you work:

$ ensemble conductor init my-project
✓ Project created successfully!

💡 Next steps:
  • Run 'ensemble edgit init' to enable component versioning
  • Run 'ensemble wrangler dev' to start the development server

$ ensemble edgit tag create my-prompt v1.0.0
✓ Tag created: prompts/my-prompt/v1.0.0

💡 Deploy this version:
  • Run 'ensemble edgit deploy set my-prompt v1.0.0 --to staging'

Environment Variables

Variable	Description
`ENSEMBLE_LOG_LEVEL`	Logging verbosity (debug, info, warn, error)
`CLOUDFLARE_API_TOKEN`	Cloudflare authentication
`ANTHROPIC_API_KEY`	Anthropic API key
`OPENAI_API_KEY`	OpenAI API key

CI/CD Integration

For CI/CD pipelines, use npx to run commands without global installation:

GitHub Actions

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Build & Deploy
        run: |
          npx @ensemble-edge/conductor build
          npx wrangler deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

GitLab CI

deploy:
  image: node:20
  script:
    - npx @ensemble-edge/conductor build
    - npx wrangler deploy
  variables:
    CLOUDFLARE_API_TOKEN: $CLOUDFLARE_API_TOKEN

Direct Product Init for CI/CD

For automated pipelines, you can also use the product-specific init commands with the -y flag to skip interactive prompts:

# Non-interactive Conductor init
npx @ensemble-edge/conductor init my-project -y

# Non-interactive Edgit init
npx @ensemble-edge/edgit init -y

Troubleshooting

Command not found after installation

Ensure your global npm/pnpm bin directory is in your PATH:

# Check where packages are installed
pnpm bin -g

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$(pnpm bin -g):$PATH"

Permission errors or installation issues

Use npx to avoid global installation entirely:

# No installation needed - just run with npx
npx @ensemble-edge/ensemble

Or use a Node version manager like nvm or fnm for global installs:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node
nvm install 20
nvm use 20

Wrangler commands not working

The Ensemble CLI passes through to Wrangler. Ensure you’re authenticated:

ensemble wrangler login
ensemble wrangler whoami

Next Steps

Quick Start

Build your first project in 5 minutes

Conductor Docs

Edge orchestration framework

Edgit Docs

Component versioning system

Cloud Docs

Managed platform

Introduction

​Overview

​Why a Unified CLI?

​Quick Start

​Getting Started

​Verify It Works

​Checking for Updates (Landscape View)

​Upgrade Command

​Upgrade Options

​Usage Examples

​Command Structure

​Available Tools

​Conductor Commands

​Global Commands

​Info Command

​Conductor Commands

​Init Options

​Start/Stop Options

​Edgit Commands

​Cloud Commands

​Configure Command

​AI Provider Setup

​Cloudflare Authentication

​How It Works

​Wrangler Commands

​Cross-Tool Discovery

​Environment Variables

​CI/CD Integration

​GitHub Actions

​GitLab CI

​Direct Product Init for CI/CD

​Troubleshooting

​Next Steps

Quick Start

Conductor Docs

Edgit Docs

Cloud Docs

Overview

Why a Unified CLI?

Quick Start

Getting Started

Verify It Works

Checking for Updates (Landscape View)

Upgrade Command

Upgrade Options

Usage Examples

Command Structure

Available Tools

Conductor Commands

Global Commands

Info Command

Conductor Commands

Init Options

Start/Stop Options

Edgit Commands

Cloud Commands

Configure Command

AI Provider Setup

Cloudflare Authentication

How It Works

Wrangler Commands

Cross-Tool Discovery

Environment Variables

CI/CD Integration

GitHub Actions

GitLab CI

Direct Product Init for CI/CD

Troubleshooting

Next Steps