CLI Commands Reference

Complete reference for the Conductor CLI.

Getting Started

No installation needed - use npx to run the CLI:

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

ensemble conductor init my-project
ensemble conductor dev
ensemble conductor validate

For CI/automated environments, use the -y flag to skip all interactive prompts:

npx @ensemble-edge/conductor init my-project -y

Global Commands

init

Initialize a new Conductor project.

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:

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

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

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

ensemble configure ai

See Configure Command for details.

configure

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

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:

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

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

What configure auth does:

Checks if already logged in to Cloudflare
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

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.

info

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

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

Command Naming: info is the official command. status is an alias that works identically.

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):

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):

ensemble conductor info --json

{
  "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.

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:

ensemble conductor dev --port 8080

This wraps npx wrangler dev. For dev containers, add --ip 0.0.0.0:

npx wrangler dev --local-protocol http --ip 0.0.0.0

deploy

Deploy to Cloudflare Workers.

ensemble conductor deploy [environment]

Options:

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

Example:

ensemble conductor deploy --env staging

test

Run tests.

pnpm test [pattern]

Options:

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

Example:

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.

pnpm run build

Options:

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

Example:

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.

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:

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

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

ensemble conductor ensemble:list --type cli

Validate Command

validate

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

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

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

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

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:

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

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:

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

ensemble conductor ensemble:list

ensemble:run

Execute an ensemble locally.

ensemble conductor ensemble:run <ensemble> [input]

Example:

ensemble conductor ensemble:run greet-user '{"name": "Alice"}'

Agent Commands

agent:list

List all agents.

ensemble conductor agent:list

agent:run

Execute an agent locally.

ensemble conductor agent:run <agent> [input]

Example:

ensemble conductor agent:run company-enricher '{"company_name": "Anthropic"}'

agent:validate

Validate agent YAML.

ensemble conductor agent:validate <file>

Component Commands

component:list

List all components.

ensemble conductor component:list

component:create

Create a new component.

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:

ensemble conductor component:create user-prompt --type prompt

Edgit Commands

edgit:init

Initialize Edgit in project.

edgit init

edgit:info

Show Edgit project info.

edgit info

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

edgit:commit

Commit changes.

edgit commit -m "message"

edgit:tag

Create version tag.

edgit tag create <component> <version>

Example:

edgit tag create my-prompt v1.2.0

edgit:log

Show commit history.

edgit log [--limit <n>]

edgit:diff

Show changes.

edgit diff [commit1] [commit2]

Config Commands

config:get

Get configuration value.

ensemble conductor config:get <key>

Example:

ensemble conductor config:get apiKey

config:set

Set configuration value.

ensemble conductor config:set <key> <value>

Example:

ensemble conductor config:set apiKey sk-...

config:list

List all configuration.

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.

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:

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

ensemble conductor keys list [options]

Options:

Option	Description
`--json`	Output as JSON

keys revoke

Revoke an API key.

ensemble conductor keys revoke <keyId> [options]

Options:

Option	Description
`--json`	Output as JSON

keys info

Show information about an API key.

ensemble conductor keys info <keyId> [options]

Options:

Option	Description
`--json`	Output as JSON

keys rotate

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

ensemble conductor keys rotate <keyId> [options]

Options:

Option	Description
`--json`	Output as JSON

Secrets Commands

secret:set

Set a secret.

ensemble conductor secret:set <name> [value]

If value is omitted, prompts securely. Example:

ensemble conductor secret:set OPENAI_API_KEY

secret:list

List secret names (not values).

ensemble conductor secret:list

secret:delete

Delete a secret.

ensemble conductor secret:delete <name>

Database Commands

db:create

Create D1 database.

ensemble conductor db:create <name>

db:migrate

Run database migrations.

ensemble conductor db:migrate [--env <environment>]

db:query

Execute SQL query.

ensemble conductor db:query <sql> [--env <environment>]

Example:

ensemble conductor db:query "SELECT * FROM users LIMIT 10"

Storage Commands

storage:create

Create KV namespace or R2 bucket.

ensemble conductor storage:create <type> <name>

Types: kv, r2, vectorize Example:

ensemble conductor storage:create kv CACHE

storage:list

List storage resources.

ensemble conductor storage:list <type>

Logs Commands

logs

Tail production logs.

npx wrangler tail [--env <environment>]

Options:

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

Example:

npx wrangler tail --filter error

Info Commands

info

Show project information.

ensemble conductor info

version

Show CLI version and scan for all Ensemble projects.

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 for the full output format.

upgrade

Interactively upgrade Ensemble packages across all discovered projects.

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 for detailed examples.

help

Show help.

ensemble conductor --help
ensemble conductor help [command]

Environment Management

env:list

List environments.

ensemble conductor env:list

env:create

Create environment.

ensemble conductor env:create <name>

env:switch

Switch active environment.

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:

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

Unified CLI

Full Ensemble CLI documentation

YAML Schema

YAML configuration reference

TypeScript API

TypeScript API reference

Your First Project

Get started

​CLI Commands Reference

​Getting Started

​Usage

​Global Commands

​init

​configure

​info

​dev

​deploy

​test

​build

​run

​Validate Command

​validate

​Bundle & Import Commands

​bundle

​import

​Ensemble Commands

​ensemble:list

​ensemble:run

​Agent Commands

​agent:list

​agent:run

​agent:validate

​Component Commands

​component:list

​component:create

​Edgit Commands

​edgit:init

​edgit:info

​edgit:commit

​edgit:tag

​edgit:log

​edgit:diff

​Config Commands

​config:get

​config:set

​config:list

​API Key Commands

​keys generate

​keys list

​keys revoke

​keys info

​keys rotate

​Secrets Commands

​secret:set

​secret:list

​secret:delete

​Database Commands

​db:create

​db:migrate

​db:query

​Storage Commands

​storage:create

​storage:list

​Logs Commands

​logs

​Info Commands

​info

​version

​upgrade

​help

​Environment Management

​env:list

​env:create

​env:switch

​Common Options

​Configuration File

​Next Steps

Unified CLI

YAML Schema

TypeScript API

Your First Project

CLI Commands Reference

Getting Started

Usage

Global Commands

init

configure

info

dev

deploy

test

build

run

Validate Command

validate

Bundle & Import Commands

bundle

import

Ensemble Commands

ensemble:list

ensemble:run

Agent Commands

agent:list

agent:run

agent:validate

Component Commands

component:list

component:create

Edgit Commands

edgit:init

edgit:info

edgit:commit

edgit:tag

edgit:log

edgit:diff

Config Commands

config:get

config:set

config:list

API Key Commands

keys generate

keys list

keys revoke

keys info

keys rotate

Secrets Commands

secret:set

secret:list

secret:delete

Database Commands

db:create

db:migrate

db:query

Storage Commands

storage:create

storage:list

Logs Commands

logs

Info Commands

info

version

upgrade

help

Environment Management

env:list

env:create

env:switch

Common Options

Configuration File

Next Steps