> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ensemble.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ensemble CLI

> One CLI to rule them all - unified access to the entire Ensemble ecosystem

## 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.

```bash theme={null}
# 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
edgit tag create component v1.0.0     # Version components
```

## Why a Unified CLI?

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

```bash theme={null}
# No installation needed - just run with npx
npx @ensemble-edge/ensemble

# Or run specific commands directly
npx @ensemble-edge/ensemble conductor init my-project
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

```bash theme={null}
# 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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
# 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
```

<Tip>
  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.
</Tip>

## Command Structure

The CLI follows a simple pattern:

```bash theme={null}
ensemble <tool> <command> [options]
```

### Available Tools

| Tool        | Description                                   | Example                             |
| ----------- | --------------------------------------------- | ----------------------------------- |
| `conductor` | Edge orchestration framework                  | `ensemble conductor init my-app`    |
| `edgit`     | Component versioning                          | `edgit tag create component 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:

```bash theme={null}
# 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
```

<Note>
  **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.
</Note>

## Conductor Commands

Create and manage Conductor projects:

```bash theme={null}
# 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 |

<Tip>
  **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.
</Tip>

<Tip>
  **Port Conflicts:** If port 8787 is in use, the command automatically finds the next available port. No more "Address already in use" errors!
</Tip>

## Edgit Commands

Version and deploy components:

```bash theme={null}
# Initialize Edgit in a repo
edgit init

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

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

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

# Tag to environment and push
edgit tag set my-prompt prod v1.0.0
edgit push --tags --force

# List component tags
edgit tag list my-prompt

# List all components
edgit components list

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

<Note>
  Since Edgit is git-native, `ensemble edgit status` passes through to `git status`. Use `ensemble edgit info` for Edgit project information.
</Note>

## Cloud Commands

Manage Ensemble Cloud resources:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
$ 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:

```bash theme={null}
$ 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:

```bash theme={null}
# 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
```

<Note>
  **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.
</Note>

## Cross-Tool Discovery

The CLI intelligently suggests related tools as you work:

```bash theme={null}
$ ensemble conductor init my-project
✓ Project created successfully!

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

```bash theme={null}
$ edgit tag create my-prompt v1.0.0
✓ Tag created: prompts/my-prompt/v1.0.0

💡 Deploy this version:
  • Run 'edgit tag set my-prompt staging v1.0.0'
  • Then 'edgit push --tags --force'
```

## 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

```yaml theme={null}
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

```yaml theme={null}
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:

```bash theme={null}
# Non-interactive Conductor init
npx @ensemble-edge/conductor init my-project -y

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

## Troubleshooting

<AccordionGroup>
  <Accordion title="Command not found after installation">
    Ensure your global npm/pnpm bin directory is in your PATH:

    ```bash theme={null}
    # Check where packages are installed
    pnpm bin -g

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

  <Accordion title="Permission errors or installation issues">
    Use `npx` to avoid global installation entirely:

    ```bash theme={null}
    # No installation needed - just run with npx
    npx @ensemble-edge/ensemble
    ```

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

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Wrangler commands not working">
    The Ensemble CLI passes through to Wrangler. Ensure you're authenticated:

    ```bash theme={null}
    ensemble wrangler login
    ensemble wrangler whoami
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/introduction/quick-start">
    Build your first project in 5 minutes
  </Card>

  <Card title="Conductor Docs" icon="network-wired" href="/conductor/overview">
    Edge orchestration framework
  </Card>

  <Card title="Edgit Docs" icon="code-branch" href="/edgit/overview">
    Component versioning system
  </Card>

  <Card title="Cloud Docs" icon="cloud" href="/cloud/overview">
    Managed platform
  </Card>
</CardGroup>