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

# CLI Commands

> Conductor command line reference

# CLI Commands Reference

**Complete reference for the Conductor CLI.**

## Getting Started

No installation needed - use `npx` to run the CLI:

```bash theme={null}
# Launch the interactive wizard
npx @ensemble-edge/ensemble

# Or run specific commands
npx @ensemble-edge/ensemble conductor init my-project
npx @ensemble-edge/ensemble conductor --help
```

## Usage

All Conductor commands are accessed through the unified Ensemble CLI:

```bash theme={null}
ensemble conductor init my-project
ensemble conductor dev
ensemble conductor validate
```

<Tip>
  **For CI/automated environments**, use the `-y` flag to skip all interactive prompts:

  ```bash theme={null}
  npx @ensemble-edge/conductor init my-project -y
  ```
</Tip>

## Global Commands

### init

Initialize a new Conductor project.

```bash theme={null}
ensemble conductor init [project-name]
```

**Options:**

| Option           | Description                                                      |
| ---------------- | ---------------------------------------------------------------- |
| `--setup <type>` | Project setup type: `full`, `starter`, `basic` (default: `full`) |
| `--examples`     | Include example agents & ensembles (same as `--setup full`)      |
| `--no-examples`  | Template only, no examples (same as `--setup starter`)           |
| `--skip-install` | Skip dependency installation                                     |
| `--pm <manager>` | Package manager: `npm`, `pnpm`, `yarn`, `bun`                    |
| `-f, --force`    | Overwrite existing directory                                     |
| `-y, --yes`      | Non-interactive mode (skip all prompts)                          |

**Setup Types:**

| Type      | Description                                                                                      |
| --------- | ------------------------------------------------------------------------------------------------ |
| `full`    | **Recommended.** Complete template with example agents, ensembles, and docs. Great for learning. |
| `starter` | Ready-to-code template without examples. Clean slate for experienced users.                      |
| `basic`   | Minimal stub for manual setup. Advanced users only.                                              |

**Examples:**

```bash theme={null}
# Interactive wizard (recommended)
ensemble conductor init my-project

# With examples (full template)
ensemble conductor init my-project --setup full

# Without examples (starter template)
ensemble conductor init my-project --setup starter
ensemble conductor init my-project --no-examples

# Minimal setup (basic)
ensemble conductor init my-project --setup basic

# Non-interactive (CI/CD mode)
ensemble conductor init my-project --yes

# With specific package manager
ensemble conductor init my-project --pm pnpm

# Force overwrite existing directory
ensemble conductor init my-project --force -y
```

**What init does:**

1. Creates project directory structure
2. Installs dependencies (`@ensemble-edge/conductor`, etc.)
3. Copies project templates (for `full` and `starter` modes)
4. Configures dev scripts for your environment
5. Provides next steps

<Tip>
  **Need to configure AI later?** If you skipped AI setup during init, you can run:

  ```bash theme={null}
  ensemble configure ai
  ```

  See [Configure Command](#configure) for details.
</Tip>

### configure

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

```bash theme={null}
ensemble configure [subcommand]
```

**Subcommands:**

| Subcommand | Description                                                    |
| ---------- | -------------------------------------------------------------- |
| `ai`       | Configure AI provider (Anthropic, OpenAI, Cloudflare AI, Groq) |
| `auth`     | Configure Cloudflare authentication (wrangler login)           |

**Options:**

| Option              | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `--provider <name>` | Pre-select AI provider (anthropic, openai, cloudflare, groq) |
| `-y, --yes`         | Skip confirmation prompts                                    |

**Examples:**

```bash theme={null}
# Interactive menu
ensemble configure

# Configure AI directly
ensemble configure ai

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

# Configure Cloudflare authentication
ensemble configure auth
```

**What configure ai does:**

1. Prompts for AI provider selection
2. Prompts for API key (except Cloudflare AI)
3. Stores secret via `wrangler secret put`
4. Enables `[ai]` binding in wrangler.toml

**What configure auth does:**

1. Checks if already logged in to Cloudflare
2. Opens browser for OAuth login if needed

**Supported Providers:**

| Provider     | Secret Name         | Notes                                 |
| ------------ | ------------------- | ------------------------------------- |
| `cloudflare` | —                   | Built-in, no API key needed           |
| `anthropic`  | `ANTHROPIC_API_KEY` | Claude models (recommended)           |
| `openai`     | `OPENAI_API_KEY`    | GPT-4 and GPT-3.5                     |
| `groq`       | `GROQ_API_KEY`      | Fast inference with Llama and Mixtral |

<Note>
  The `configure` command requires a `wrangler.toml` file. Run it from your project directory after `init`. The same wizards are used during `ensemble conductor init` to ensure consistency.
</Note>

***

### info

Show comprehensive project info including configuration, components, triggers, Cloudflare services, and deployment health.

```bash theme={null}
ensemble conductor info [options]
```

**Options:**

| Option              | Description                       |
| ------------------- | --------------------------------- |
| `--json`            | Output as JSON (for CI/scripting) |
| `--compact`         | Compact single-line format        |
| `--no-health-check` | Skip worker health ping           |

<Note>
  **Command Naming:** `info` is the official command. `status` is an alias that works identically.
</Note>

**Example Output (Full):**

```
┌─────────────────────┐
│ 🎼 Conductor Info   │
└─────────────────────┘

Project
  Name:             my-project
  Version:          1.2.3
  Conductor:        @ensemble-edge/conductor@2.4.0
  Environment:      development (local)

Configuration
  conductor.config: ✓ Found
  wrangler.toml:    ✓ Found

Components
  Agents:           12 (10 custom)
  Ensembles:        5
  Other:            30 (8 prompts, 6 schemas, 5 configs, ...)

Triggers
  HTTP routes:      8
  Webhooks:         2
  MCP tools:        3
  Cron jobs:        1

Security
  requireAuth:      ✓ true
  stealthMode:      ○ false
  allowDirectAgentExecution: ✓ true

┌─────────────────────────┐
│ ☁️  Cloudflare Services │
└─────────────────────────┘

AI & Intelligence
  ✓ Workers AI:       Configured              [AI]
  ○ AI Gateway:       Not configured
  ✓ Vectorize:        my-index                [VECTORIZE]

Storage
  ✓ KV:               2 configured            [CACHE, SESSIONS]
  ✓ D1:               my-db                   [DB]
  ○ R2:               Not configured

Compute & State
  ✓ Durable Objects:  2 configured            [EXEC, HITL]
  ○ Queues:           Not configured
  ○ Hyperdrive:       Not configured

┌───────────────┐
│ 🌐 Deployment │
└───────────────┘

  Worker URL:       https://my-project.workers.dev
  Status:           ✓ Reachable (v2.4.0)

  Ensemble Cloud:   ○ Not connected
  Pulse:            ✓ Enabled

Docs: https://docs.ensemble.ai/conductor
```

**Example Output (Compact):**

```bash theme={null}
ensemble conductor info --compact
```

```
🎼 Conductor Info

Project:     my-project v1.2.3 (@ensemble-edge/conductor@2.4.0)
Environment: development (local)

Components:  47 total (12 agents, 5 ensembles, 30 other)
Triggers:    8 http │ 2 webhook │ 3 mcp │ 1 cron

Cloudflare
  ✓ Workers AI    ✓ KV (2)        ✓ D1           ○ Analytics
  ○ AI Gateway    ○ R2            ✓ DO (2)       ○ Queues
  ✓ Vectorize     ○ Hyperdrive

Worker:      ✓ https://my-project.workers.dev (v2.4.0)
Cloud:       ○ Not connected
Pulse:       ✓ Enabled
```

**Example Output (JSON):**

```bash theme={null}
ensemble conductor info --json
```

```json theme={null}
{
  "project": {
    "name": "my-project",
    "version": "1.2.3",
    "conductorVersion": "2.4.0"
  },
  "config": {
    "conductorConfig": true,
    "wranglerConfig": true
  },
  "environment": "development",
  "components": {
    "agents": { "total": 12, "custom": 10, "builtIn": 2 },
    "ensembles": 5,
    "prompts": 8
  },
  "triggers": {
    "http": 8,
    "webhook": 2,
    "mcp": 3,
    "cron": 1
  },
  "cloudflare": {
    "workersAI": { "configured": true, "bindings": ["AI"] },
    "kv": { "configured": true, "count": 2, "bindings": ["CACHE", "SESSIONS"] }
  },
  "deployment": {
    "workerUrl": "https://my-project.workers.dev",
    "health": { "ok": true, "version": "2.4.0" },
    "cloudEnabled": false,
    "pulse": true
  }
}
```

***

### dev

Start local development server.

```bash theme={null}
ensemble conductor dev
```

Options:

* `--port, -p <port>` - Port number (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

Example:

```bash theme={null}
ensemble conductor dev --port 8080
```

<Note>
  This wraps `npx wrangler dev`. For dev containers, add `--ip 0.0.0.0`:

  ```bash theme={null}
  npx wrangler dev --local-protocol http --ip 0.0.0.0
  ```
</Note>

### deploy

Deploy to Cloudflare Workers.

```bash theme={null}
ensemble conductor deploy [environment]
```

Options:

* `--env <environment>` - Environment name (default: production)
* `--dry-run` - Show what would be deployed

Example:

```bash theme={null}
ensemble conductor deploy --env staging
```

### test

Run tests.

```bash theme={null}
pnpm test [pattern]
```

Options:

* `--watch` - Watch mode
* `--coverage` - Generate coverage report
* `--verbose` - Verbose output

Example:

```bash theme={null}
pnpm test --coverage
```

### build

Execute all build triggers in the project. Build triggers run at build time to generate static assets like documentation, OpenAPI specs, or pre-rendered pages.

```bash theme={null}
pnpm run build
```

Options:

* `--env <environment>` - Target environment (default: production)
* `--output <path>` - Override output directory
* `--verbose` - Verbose output

Example:

```bash theme={null}
pnpm run build --env staging --verbose
```

**What it does:**

* Finds all ensembles with `type: build` triggers
* Executes them sequentially
* Outputs generated files to configured directories
* Reports build status and timing

**Common Use Cases:**

* `pnpm run build` before deployment (CI/CD)
* Generate OpenAPI documentation
* Pre-render static pages
* Build search indexes

### run

Execute a CLI trigger by command name. CLI triggers are custom commands defined in ensemble YAML files.

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

**Arguments:**

| Argument  | Description                                             |
| --------- | ------------------------------------------------------- |
| `command` | Name of the CLI command to run (from `trigger.command`) |

**Options:**

Options are defined in the ensemble's CLI trigger configuration. They can be:

* `--<option-name> <value>` - For string/number options
* `--<flag-name>` - For boolean flags
* Multiple values supported for array options

Example:

```bash theme={null}
# Run a CLI command with options
ensemble conductor run generate-docs --output ./docs --format markdown --verbose

# Run with required and optional parameters
ensemble conductor run import-data --file data.json --batch-size 100

# Boolean flags
ensemble conductor run deploy --dry-run --skip-tests
```

**Defining CLI Commands:**

```yaml theme={null}
# ensembles/my-cli.yaml
ensemble: my-cli
trigger:
  - type: cli
    command: generate-docs
    description: Generate project documentation
    options:
      - name: output
        type: string
        required: true
        description: Output directory
      - name: format
        type: string
        default: markdown
        description: Output format (markdown, html, pdf)
      - name: verbose
        type: boolean
        default: false
        description: Enable verbose output

flow:
  - agent: docs-generator
    input:
      output: ${trigger.options.output}
      format: ${trigger.options.format}
      verbose: ${trigger.options.verbose}
```

**Listing Available Commands:**

```bash theme={null}
ensemble conductor ensemble:list --type cli
```

## Validate Command

### validate

Validate ensemble and agent configuration files (YAML or TypeScript).

```bash theme={null}
ensemble conductor validate [path] [options]
```

**Arguments:**

| Argument | Description                                                        |
| -------- | ------------------------------------------------------------------ |
| `path`   | Path to file or directory to validate (default: current directory) |

**Options:**

| Option              | Description                                     |
| ------------------- | ----------------------------------------------- |
| `--fix`             | Automatically fix fixable issues                |
| `-r, --recursive`   | Recursively validate directories                |
| `--strict`          | Enable strict validation mode                   |
| `--format <format>` | Output format: `text`, `json` (default: `text`) |

**Supported File Types:**

* `.yaml`, `.yml` - YAML ensemble and agent definitions
* `.ts` - TypeScript agents and ensembles

**TypeScript Agent Validation:**

The validate command checks TypeScript agent files for:

* **Default export** - Must export a default handler function
* **Function signature** - Should accept `AgentExecutionContext`
* **Return type** - Should return a value or Promise

```bash theme={null}
# Validate a TypeScript agent
ensemble conductor validate agents/my-agent/index.ts
```

Example output for common issues:

```
✗ agents/my-agent/index.ts
  No default export found. TypeScript agents must export a default function:

  export default async function(context: AgentExecutionContext) {
    // your code here
  }
```

**Examples:**

```bash theme={null}
# Validate current directory
ensemble conductor validate

# Validate specific file
ensemble conductor validate ensembles/workflow.yaml
ensemble conductor validate agents/custom-agent/index.ts

# Validate with auto-fix
ensemble conductor validate --fix

# Validate recursively with JSON output
ensemble conductor validate . -r --format json
```

***

## Bundle & Import Commands

### bundle

Export an ensemble or agent with all its dependencies into a portable archive.

```bash theme={null}
ensemble conductor bundle <type> <name> [options]
```

**Arguments:**

| Argument | Description                             |
| -------- | --------------------------------------- |
| `type`   | Type to bundle: `ensemble` or `agent`   |
| `name`   | Name of the ensemble or agent to bundle |

**Options:**

| Option                  | Description                                |
| ----------------------- | ------------------------------------------ |
| `-o, --output <path>`   | Output file path                           |
| `--format <format>`     | Archive format: `tar` (default) or `zip`   |
| `--dry-run`             | Preview what would be bundled              |
| `--agents-dir <dir>`    | Agents directory (default: `agents`)       |
| `--ensembles-dir <dir>` | Ensembles directory (default: `ensembles`) |
| `--prompts-dir <dir>`   | Prompts directory (default: `prompts`)     |

**Examples:**

```bash theme={null}
# Bundle an ensemble
ensemble conductor bundle ensemble my-workflow -o my-workflow.tar.gz

# Bundle an agent
ensemble conductor bundle agent company-enricher --format zip

# Preview bundle contents
ensemble conductor bundle ensemble rag-pipeline --dry-run
```

### import

Import a bundled ensemble or agent into the current project.

```bash theme={null}
ensemble conductor import <bundle> [options]
```

**Arguments:**

| Argument | Description                               |
| -------- | ----------------------------------------- |
| `bundle` | Path to bundle file (`.tar.gz` or `.zip`) |

**Options:**

| Option                  | Description                                |
| ----------------------- | ------------------------------------------ |
| `-f, --force`           | Overwrite existing files without prompting |
| `-s, --skip`            | Skip existing files without prompting      |
| `--dry-run`             | Preview import without writing files       |
| `--target-dir <dir>`    | Target directory (default: `.`)            |
| `--ensembles-dir <dir>` | Ensembles directory (default: `ensembles`) |
| `--agents-dir <dir>`    | Agents directory (default: `agents`)       |
| `--prompts-dir <dir>`   | Prompts directory (default: `prompts`)     |

**Examples:**

```bash theme={null}
# Import a bundle
ensemble conductor import ./my-workflow.tar.gz

# Preview import
ensemble conductor import ./shared-agent.zip --dry-run

# Force overwrite existing files
ensemble conductor import ./updated-workflow.tar.gz --force

# Skip conflicts
ensemble conductor import ./new-agents.tar.gz --skip
```

***

## Ensemble Commands

### ensemble:list

List all ensembles.

```bash theme={null}
ensemble conductor ensemble:list
```

### ensemble:run

Execute an ensemble locally.

```bash theme={null}
ensemble conductor ensemble:run <ensemble> [input]
```

Example:

```bash theme={null}
ensemble conductor ensemble:run greet-user '{"name": "Alice"}'
```

## Agent Commands

### agent:list

List all agents.

```bash theme={null}
ensemble conductor agent:list
```

### agent:run

Execute an agent locally.

```bash theme={null}
ensemble conductor agent:run <agent> [input]
```

Example:

```bash theme={null}
ensemble conductor agent:run company-enricher '{"company_name": "Anthropic"}'
```

### agent:validate

Validate agent YAML.

```bash theme={null}
ensemble conductor agent:validate <file>
```

## Component Commands

### component:list

List all components.

```bash theme={null}
ensemble conductor component:list
```

### component:create

Create a new component.

```bash theme={null}
ensemble conductor component:create <name> --type <type>
```

Options:

* `--type <type>` - Component type (prompt, template, schema, config)
* `--version <version>` - Initial version (default: v1.0.0)

Example:

```bash theme={null}
ensemble conductor component:create user-prompt --type prompt
```

## Edgit Commands

### edgit:init

Initialize Edgit in project.

```bash theme={null}
edgit init
```

### edgit:info

Show Edgit project info.

```bash theme={null}
edgit info
```

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

### edgit:commit

Commit changes.

```bash theme={null}
edgit commit -m "message"
```

### edgit:tag

Create version tag.

```bash theme={null}
edgit tag create <component> <version>
```

Example:

```bash theme={null}
edgit tag create my-prompt v1.2.0
```

### edgit:log

Show commit history.

```bash theme={null}
edgit log [--limit <n>]
```

### edgit:diff

Show changes.

```bash theme={null}
edgit diff [commit1] [commit2]
```

## Config Commands

### config:get

Get configuration value.

```bash theme={null}
ensemble conductor config:get <key>
```

Example:

```bash theme={null}
ensemble conductor config:get apiKey
```

### config:set

Set configuration value.

```bash theme={null}
ensemble conductor config:set <key> <value>
```

Example:

```bash theme={null}
ensemble conductor config:set apiKey sk-...
```

### config:list

List all configuration.

```bash theme={null}
ensemble conductor config:list
```

## API Key Commands

Manage API keys for authentication. Keys are stored in Cloudflare KV.

### keys generate

Generate a new API key with optional scoped permissions.

```bash theme={null}
ensemble conductor keys generate --name <name> [options]
```

**Options:**

| Option                  | Description                                              |
| ----------------------- | -------------------------------------------------------- |
| `--name <name>`         | Human-readable name for the key (required)               |
| `--permissions <perms>` | Comma-separated permissions (default: `*`)               |
| `--expires <duration>`  | Expiration: `30d`, `90d`, `1y`, `never` (default: `90d`) |
| `--user-id <userId>`    | User/service ID this key belongs to                      |
| `--json`                | Output as JSON                                           |

**Examples:**

```bash theme={null}
# Full access key
ensemble conductor keys generate --name "admin" --permissions "*"

# Scoped key for billing ensembles
ensemble conductor keys generate \
  --name "billing-service" \
  --permissions "ensemble:billing-*:execute,ensemble:invoice-*:execute" \
  --expires "90d"

# Key that never expires
ensemble conductor keys generate --name "internal" --permissions "*" --expires never
```

### keys list

List all API keys.

```bash theme={null}
ensemble conductor keys list [options]
```

**Options:**

| Option   | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### keys revoke

Revoke an API key.

```bash theme={null}
ensemble conductor keys revoke <keyId> [options]
```

**Options:**

| Option   | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### keys info

Show information about an API key.

```bash theme={null}
ensemble conductor keys info <keyId> [options]
```

**Options:**

| Option   | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### keys rotate

Rotate an API key (generates new key, keeps metadata).

```bash theme={null}
ensemble conductor keys rotate <keyId> [options]
```

**Options:**

| Option   | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

***

## Secrets Commands

### secret:set

Set a secret.

```bash theme={null}
ensemble conductor secret:set <name> [value]
```

If value is omitted, prompts securely.

Example:

```bash theme={null}
ensemble conductor secret:set OPENAI_API_KEY
```

### secret:list

List secret names (not values).

```bash theme={null}
ensemble conductor secret:list
```

### secret:delete

Delete a secret.

```bash theme={null}
ensemble conductor secret:delete <name>
```

## Database Commands

### db:create

Create D1 database.

```bash theme={null}
ensemble conductor db:create <name>
```

### db:migrate

Run database migrations.

```bash theme={null}
ensemble conductor db:migrate [--env <environment>]
```

### db:query

Execute SQL query.

```bash theme={null}
ensemble conductor db:query <sql> [--env <environment>]
```

Example:

```bash theme={null}
ensemble conductor db:query "SELECT * FROM users LIMIT 10"
```

## Storage Commands

### storage:create

Create KV namespace or R2 bucket.

```bash theme={null}
ensemble conductor storage:create <type> <name>
```

Types: `kv`, `r2`, `vectorize`

Example:

```bash theme={null}
ensemble conductor storage:create kv CACHE
```

### storage:list

List storage resources.

```bash theme={null}
ensemble conductor storage:list <type>
```

## Logs Commands

### logs

Tail production logs.

```bash theme={null}
npx wrangler tail [--env <environment>]
```

Options:

* `--env <environment>` - Environment name
* `--follow` - Follow logs in real-time
* `--filter <pattern>` - Filter by pattern

Example:

```bash theme={null}
npx wrangler tail --filter error
```

## Info Commands

### info

Show project information.

```bash theme={null}
ensemble conductor info
```

### version

Show CLI version and scan for all Ensemble projects.

```bash theme={null}
ensemble --version
```

The version command now scans your workspace and displays:

* Tree view of all discovered Ensemble projects (Conductor, Edgit)
* Installed packages and their versions per project
* Latest available versions from npm
* Update status indicators (✓ up-to-date, ⬆ update available)

See [Checking for Updates](/introduction/ensemble-cli#checking-for-updates-landscape-view) for the full output format.

### upgrade

Interactively upgrade Ensemble packages across all discovered projects.

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

See [Upgrade Command](/introduction/ensemble-cli#upgrade-command) for detailed examples.

### help

Show help.

```bash theme={null}
ensemble conductor --help
ensemble conductor help [command]
```

## Environment Management

### env:list

List environments.

```bash theme={null}
ensemble conductor env:list
```

### env:create

Create environment.

```bash theme={null}
ensemble conductor env:create <name>
```

### env:switch

Switch active environment.

```bash theme={null}
ensemble conductor env:switch <name>
```

## Common Options

Most commands support these options:

* `--help` - Show help
* `--verbose` - Verbose output
* `--quiet` - Quiet output
* `--env <environment>` - Target environment
* `--config <path>` - Config file path

## Configuration File

Commands read from `conductor.config.js`:

```javascript theme={null}
export default {
  name: 'my-project',
  environments: {
    production: {
      accountId: 'abc123...',
      bindings: {
        KV: 'namespace-id',
        DB: 'database-id'
      }
    },
    staging: {
      accountId: 'abc123...',
      bindings: {
        KV: 'staging-namespace-id',
        DB: 'staging-database-id'
      }
    }
  }
};
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Unified CLI" icon="terminal" href="/introduction/ensemble-cli">
    Full Ensemble CLI documentation
  </Card>

  <Card title="YAML Schema" icon="file-code" href="/conductor/reference/yaml-schema">
    YAML configuration reference
  </Card>

  <Card title="TypeScript API" icon="code" href="/conductor/reference/ts-schema">
    TypeScript API reference
  </Card>

  <Card title="Your First Project" icon="rocket" href="/conductor/getting-started/your-first-project">
    Get started
  </Card>
</CardGroup>