CLI Commands - Ensemble Edge

Getting Started

No installation needed - use npx to run Edgit:

# Using npx (no install needed)
npx @ensemble-edge/edgit init
npx @ensemble-edge/edgit tag create my-prompt v1.0.0

# Or if edgit is installed globally
edgit init
edgit tag create my-prompt v1.0.0

For CI/CD pipelines, use npx @ensemble-edge/edgit init -y to skip interactive prompts.

Global

`edgit --version`

Show Edgit version:

edgit --version
# Output: edgit v0.4.4

For a landscape view showing all Ensemble projects with update status, use ensemble --version. To upgrade Edgit across multiple projects, use ensemble upgrade. See Ensemble CLI for details.

`edgit --help`

Show help:

edgit --help
edgit <command> --help  # Help for specific command

Info

`ensemble edgit info`

View comprehensive Edgit project info including initialization state, tracked components, recent versions, and deployments:

ensemble edgit info [options]

Options:

Option	Description
`--json`	Output as JSON (for CI/scripting)
`--compact`	Compact single-line format

Example Output (Full):

┌─────────────────────────────┐
│ ✓ 📦 Edgit Info             │
│                             │
│ Semantic versioning for     │
│ AI components               │
└─────────────────────────────┘

Repository
  Git Repo:         ✓ Initialized
  Edgit:            ✓ Initialized
  Components:       12 tracked (3 untracked)

Recent Versions (5 of 24 total)
  components/prompts/extraction/v1.2.0    2024-11-15
  components/configs/api-config/v2.0.1    2024-11-14
  components/ensembles/data-pipeline/v1.0.0      2024-11-12
  logic/agents/scraper/v3.1.0             2024-11-10
  components/prompts/analysis/v1.0.0      2024-11-08

Deployments
  extraction        prod: v1.2.0    staging: v1.1.0
  api-config        prod: v2.0.1    staging: v2.0.1
  data-pipeline     prod: v1.0.0    staging: v1.0.0

Docs: https://docs.ensemble.ai/edgit

Example Output (Compact):

ensemble edgit info --compact

📦 Edgit Info

Git:         ✓ Initialized
Edgit:       ✓ Initialized
Components:  12 tracked
Versions:    24 total

Example Output (JSON):

ensemble edgit info --json

{
  "gitRepo": true,
  "initialized": true,
  "components": {
    "tracked": 12,
    "untracked": 3
  },
  "versions": {
    "total": 24,
    "recent": [
      {
        "tag": "components/prompts/extraction/v1.2.0",
        "date": "2024-11-15"
      },
      {
        "tag": "components/configs/api-config/v2.0.1",
        "date": "2024-11-14"
      }
    ]
  },
  "deployments": [
    {
      "component": "extraction",
      "prod": "v1.2.0",
      "staging": "v1.1.0"
    }
  ]
}

Command Naming: The official command is info. Using ensemble edgit status will pass through to git status since Edgit is git-native. Use info for Edgit project information.

`edgit info` (Direct CLI)

You can also run the info command directly via the Edgit CLI:

npx @ensemble-edge/edgit info [options]
# or
edgit info [options]

The info command provides the same data whether called via Ensemble CLI or directly. The Ensemble CLI adds visual styling (banners, colors, boxes) for a richer experience.

Initialization

`edgit init`

Initialize Edgit in your repository:

edgit init

Creates:

.edgit/components.json - Component registry
Initial directory structure

Requirements: Must be in a Git repository

Component Registry

`edgit components add`

edgit components add <type> <name> <path> [options]

Arguments:

type - Component type (prompt, config, query, script, template, docs, agent, ensemble, tool, schema)
name - Unique component name
path - File path relative to repo root

Options:

--description - Human-readable description

Examples:

# Register prompt
edgit components add prompt extraction components/prompts/extraction.md

# Register config
edgit components add config api-config components/configs/api.json

# Register query
edgit components add query analytics-query components/queries/analytics.sql

# Register script
edgit components add script transform components/scripts/transform.ts

# Register template
edgit components add template header components/templates/header.html

# Register docs
edgit components add docs getting-started components/docs/getting-started.md

# Register agent
edgit components add agent scraper agents/scraper/

# Register TypeScript ensemble
edgit components add ensemble data-pipeline ensembles/data-pipeline.ts

# Register YAML ensemble
edgit components add ensemble scraping-workflow ensembles/scraping.yaml

`edgit components list`

List all components:

edgit components list [options]

Options:

--format <type> - Output format (tree, table, json, yaml)
--type <type> - Filter by type
--untracked - Show untracked components

Examples:

# Tree view (default)
edgit components list --format tree
# Output:
# extraction (prompt)
#  v1.0.0 [prod]
#  v0.9.0 [staging]
#  v0.1.0

# Table view
edgit components list --format table
# Output:
# Component    Type    Latest   Prod     Staging
# extraction   prompt  v1.0.0   v1.0.0   v0.9.0

# JSON (for scripts)
edgit components list --format json

# Filter by type
edgit components list --type prompt

# Filter by ensemble type
edgit components list --type ensemble

# Show untracked
edgit components list --untracked

`edgit components remove`

Remove a component from registry:

edgit components remove <name>

Note: Doesn’t delete files, just removes from registry

Versioning

Tag Format

Edgit uses a 4-level tag format:

{prefix}/{type}/{name}/{slot}

prefix - components or logic (inferred from file location)
type - prompts, agents, schemas, etc.
name - Component name
slot - Version (e.g., v1.0.0) or environment (e.g., production, staging)

Examples:

components/prompts/extraction/v1.0.0
components/prompts/extraction/production
components/schemas/user/v2.1.0
logic/agents/classifier/staging
logic/agents/classifier/v1.5.0

Type-Specific Tag Namespaces

Each component type gets its own namespace in the 4-level format:

Component Type	Tag Example
`prompt`	`components/prompts/extraction/v1.0.0`
`schema`	`components/schemas/user/v1.0.0`
`config`	`components/configs/api/v1.0.0`
`script`	`components/scripts/transform/v1.0.0`
`query`	`components/queries/analytics/v1.0.0`
`template`	`components/templates/email/v1.0.0`
`tool`	`components/tools/calculator/v1.0.0`
`agent`	`logic/agents/scraper/v1.0.0`
`ensemble`	`components/ensembles/pipeline/v1.0.0`

The prefix (components or logic) is automatically inferred from the component’s file location.

`edgit tag create`

Create a version tag:

edgit tag create <name> <version> [options]

Arguments:

name - Component name
version - Semantic version (v..)

Options:

-m <message> - Tag message

Examples:

# Version a component
edgit tag create extraction v1.0.0

# Version with message
edgit tag create extraction v1.0.0 -m "Initial stable release"

# Version an agent (prefix inferred from location)
edgit tag create scraper v1.5.0

# Version an ensemble
edgit tag create data-pipeline v1.0.0 -m "Added parallel processing"

Version tags are immutable and don’t require --force to push.

`edgit tag bump`

Bump the version of a component based on semantic versioning:

edgit tag bump <component> <level> [--ref <ref>]

Arguments:

component - Component name
level - Bump level: major, minor, patch, or prerelease

Options:

--ref <ref> - Git ref to tag (default: HEAD)

Bump Types:

Level	Example
`major`	v1.2.3 → v2.0.0
`minor`	v1.2.3 → v1.3.0
`patch`	v1.2.3 → v1.2.4
`prerelease`	v1.2.3 → v1.2.4-0, v1.2.4-0 → v1.2.4-1

Examples:

# Bump patch version (v1.2.3 → v1.2.4)
edgit tag bump extraction patch

# Bump minor version (v1.2.3 → v1.3.0)
edgit tag bump extraction minor

# Bump major version (v1.2.3 → v2.0.0)
edgit tag bump extraction major

# Create prerelease (v1.2.3 → v1.2.4-0)
edgit tag bump extraction prerelease

# Bump at specific commit
edgit tag bump extraction patch --ref abc1234

Output:

Latest version: v1.2.3
Bumping: patch

✅ Created tag: extraction@v1.2.4
   Git tag: components/prompts/extraction/v1.2.4
   Points to: abc1234

Push to deploy:
  edgit push --tags

Use edgit tag bump in CI/CD pipelines to automatically increment versions when components change.

`edgit tag set`

Create or move a mutable environment tag:

edgit tag set <component> <environment> [ref]

Arguments:

component - Component name
environment - Environment name (production, staging, dev, etc.)
ref - Optional git ref (default: HEAD)

Examples:

# Set staging to current HEAD
edgit tag set extraction staging

# Set production to a specific version
edgit tag set extraction production v1.0.0

# Set from a branch
edgit tag set extraction staging feature-branch

# Agent environment tags
edgit tag set classifier staging HEAD

Environment tags are mutable and require --force when pushing if the tag has moved: edgit push --tags --force

List versions of a component:

edgit tag list <name> [options]

Options:

--with-dates - Include creation dates
--format <type> - Output format (text, json). Default: text

Examples:

# List versions
edgit tag list extraction
# Output:
# v1.0.0
# v1.0.1
# v1.1.0

# With dates
edgit tag list extraction --with-dates
# Output:
# v1.0.0 (2024-10-15)
# v1.0.1 (2024-10-18)
# v1.1.0 (2024-10-25)

# JSON output (useful for scripting and CI/CD)
edgit tag list extraction --format json
# Output:
# {
#   "name": "extraction",
#   "type": "prompt",
#   "namespace": "components/prompts",
#   "versions": [
#     {"version": "v1.0.0", "date": "2024-10-15T10:30:00Z"},
#     {"version": "v1.0.1", "date": "2024-10-18T14:22:00Z"},
#     {"version": "v1.1.0", "date": "2024-10-25T09:15:00Z"}
#   ]
# }

`edgit tag show`

Show details of a specific version:

edgit tag show <name>@<version> [options]

Options:

--format <type> - Output format (text, json). Default: text

Examples:

# Show version details
edgit tag show extraction@v1.0.0
# Output:
# Tag: components/prompts/extraction/v1.0.0
# Date: 2024-10-15T10:30:00Z
# Author: John Doe <john@example.com>
# Message: Initial stable release

# JSON output (useful for CI/CD pipelines)
edgit tag show extraction@v1.0.0 --format json
# Output:
# {
#   "name": "extraction",
#   "version": "v1.0.0",
#   "type": "prompt",
#   "namespace": "components/prompts",
#   "tag": "components/prompts/extraction/v1.0.0",
#   "sha": "abc123...",
#   "date": "2024-10-15T10:30:00Z",
#   "author": "John Doe <john@example.com>",
#   "message": "Initial stable release"
# }

`edgit tag delete`

Delete a version tag:

edgit tag delete <name> <version>

Caution: This deletes the Git tag. Use sparingly.

Push

`edgit push`

Push commits and tags to remote:

edgit push                    # Push commits only
edgit push --tags             # Push commits + all tags
edgit push --tags --force     # Push with force (for moved environment tags)

Examples:

# Push commits only
edgit push

# Push commits and all tags
edgit push --tags

# Push with force (needed when moving environment tags)
edgit push --tags --force

Use --force when pushing moved environment tags (production, staging, etc.). Version tags are immutable and never need --force.

Discovery

`edgit discover scan`

Scan repository for components:

edgit discover scan [options]

Options:

--type <type> - Filter by type (prompt, config, query, script, agent, ensemble)
--register - Automatically register discovered components
--changed - Only scan files changed since last commit (useful for CI/CD)
--since <ref> - Git ref to compare against (default: HEAD~1). Use with —changed
--tracked-only - Only scan git-tracked files
--output <format> - Output format: table (default), json, simple

Examples:

# Scan for all components
edgit discover scan
# Output:
# Found 15 components:
# - components/prompts/extraction.md (prompt)
# - components/configs/api.json (config)
# - ensembles/data-pipeline.ts (ensemble)
# ...

# Scan for prompts only
edgit discover scan --type prompt

# Scan for TypeScript ensembles
edgit discover scan --type ensemble
# Found 5 ensemble files:
# - ensembles/data-pipeline.ts
# - ensembles/scraping-workflow.ts
# - ensembles/rag-pipeline.yaml

# Scan only changed files (for CI/CD)
edgit discover scan --changed
# Only scans files changed since HEAD~1

# Scan changes since a specific branch
edgit discover scan --changed --since main
# Only scans files changed since main branch

# Scan and register
edgit discover scan --register

# JSON output for scripting
edgit discover scan --changed --output json

`edgit discover detect`

Detect component type of a file:

edgit discover detect <file>

Examples:

# Detect file type
edgit discover detect src/transform.ts
# Output:
# Type: script
# Confidence: 95%
# Suggested name: transform

# Detect TypeScript ensemble
edgit discover detect ensembles/data-pipeline.ts
# Output:
# Type: ensemble
# Confidence: 95%
# Suggested name: data-pipeline

# Get just the name
edgit discover detect src/transform.ts --name-only
# Output: transform

`edgit discover patterns list`

List component detection patterns:

edgit discover patterns list [options]

Options:

--format <type> - Output format (text, json). Default: text

Examples:

# List detection patterns
edgit discover patterns list
# Output:
# prompt: *.md in prompts/, components/prompts/
# config: *.json, *.yaml in configs/, components/configs/
# schema: *.json in schemas/, components/schemas/
# ...

# JSON output (useful for scripting and tooling)
edgit discover patterns list --format json
# Output:
# {
#   "patterns": [
#     {"type": "prompt", "extensions": [".md"], "directories": ["prompts/", "components/prompts/"]},
#     {"type": "config", "extensions": [".json", ".yaml"], "directories": ["configs/", "components/configs/"]},
#     {"type": "schema", "extensions": [".json"], "directories": ["schemas/", "components/schemas/"]},
#     ...
#   ]
# }

Git Pass-Through

All git commands work with Edgit:

# Standard git commands via edgit
edgit add .
edgit commit -m "message"
edgit pull
edgit checkout -b feature
edgit merge main
edgit status
edgit log
edgit diff

For standard git operations, you can also use git directly. The pass-through is convenient when you’re already working with edgit commands.

Version Management

Edgit uses explicit Git tags for versioning. To get the latest version for a component:

# List all versions for a component
edgit tag list my-prompt

# Show details for a specific version
edgit tag show my-prompt@v1.2.3

For CI/CD automation, use shell commands to calculate version bumps:

# Get latest version
LATEST=$(edgit tag list my-prompt --format json | jq -r '.versions[-1] // "v0.0.0"')

# Bump patch version (v1.2.3 → v1.2.4)
NEW=$(echo $LATEST | awk -F. '{$NF = $NF + 1;} 1' | sed 's/ /./g')

# Create new version
edgit tag create my-prompt $NEW

Environment Variables

Edgit respects these environment variables:

`OPENAI_API_KEY`

OpenAI API key for AI-powered commit messages:

export OPENAI_API_KEY=sk-...
edgit commit  # AI generates message

`EDGIT_REGISTRY_PATH`

Custom registry path (default: .edgit/components.json):

export EDGIT_REGISTRY_PATH=.custom/registry.json

`EDGIT_AUTO_PUSH`

Automatically push tags after creating them:

export EDGIT_AUTO_PUSH=true
edgit tag create my-prompt v1.0.0  # Automatically pushes

Exit Codes

0 - Success
1 - General error
2 - Invalid arguments
3 - Git repository not found
4 - Component not found
5 - Version already exists
6 - Version not found

Common Workflows

Register and Version

# 1. Register component
edgit components add prompt extraction components/prompts/extraction.md

# 2. Create version
edgit tag create extraction v1.0.0

# 3. Push tag
edgit push --tags

Deploy Pipeline

# 1. Deploy to staging
edgit tag set extraction staging v1.0.0
edgit push --tags --force

# 2. Test in staging...

# 3. Promote to production
edgit tag set extraction production v1.0.0
edgit push --tags --force

Rollback

# 1. Check version history
edgit tag list extraction --with-dates

# 2. See details of a specific version
edgit tag show extraction@v0.9.0

# 3. Rollback to previous version
edgit tag set extraction production v0.9.0
edgit push --tags --force

Discovery

# 1. Scan for components
edgit discover scan

# 2. Register interesting ones
edgit components add prompt analysis components/prompts/analysis.md

# 3. Version them
edgit tag create analysis v1.0.0

Tips

Aliases

Add to your .bashrc or .zshrc for convenience:

alias edgit='npx @ensemble-edge/edgit'
alias et='edgit tag create'
alias ed='edgit tag set'

Auto-Completion

Generate completion script:

edgit completion bash > /etc/bash_completion.d/edgit  # Bash
edgit completion zsh > ~/.zsh/completion/_edgit       # Zsh

Scripting

Use --format json for scripts:

#!/bin/bash
COMPONENTS=$(edgit components list --format json)
echo $COMPONENTS | jq '.[] | select(.type == "prompt") | .name'

Next Steps

Unified CLI

Full Ensemble CLI documentation

Basic Usage

Essential commands and workflows

Versioning Guide

Master versioning strategies

CI/CD Integration

Automate in your pipeline

​Getting Started

​Global

​edgit --version

​edgit --help

​Info

​ensemble edgit info

​edgit info (Direct CLI)

​Initialization

​edgit init

​Component Registry

​edgit components add

​edgit components list

​edgit components remove

​Versioning

​Tag Format

​Type-Specific Tag Namespaces

​edgit tag create

​edgit tag bump

​edgit tag set

​edgit tag list

​edgit tag show

​edgit tag delete

​Push

​edgit push

​Discovery

​edgit discover scan

​edgit discover detect

​edgit discover patterns list

​Git Pass-Through

​Version Management

​Environment Variables

​OPENAI_API_KEY

​EDGIT_REGISTRY_PATH

​EDGIT_AUTO_PUSH

​Exit Codes

​Common Workflows

​Register and Version

​Deploy Pipeline

​Rollback

​Discovery

​Tips

​Aliases

​Auto-Completion

​Scripting

​Next Steps

Unified CLI

Basic Usage

Versioning Guide

CI/CD Integration

Getting Started

Global

`edgit --version`

`edgit --help`

Info

`ensemble edgit info`

`edgit info` (Direct CLI)

Initialization

`edgit init`

Component Registry

`edgit components add`

`edgit components list`

`edgit components remove`

Versioning

Tag Format

Type-Specific Tag Namespaces

`edgit tag create`

`edgit tag bump`

`edgit tag set`

`edgit tag list`

`edgit tag show`

`edgit tag delete`

Push

`edgit push`

Discovery

`edgit discover scan`

`edgit discover detect`

`edgit discover patterns list`

Git Pass-Through

Version Management

Environment Variables

`OPENAI_API_KEY`

`EDGIT_REGISTRY_PATH`

`EDGIT_AUTO_PUSH`

Exit Codes

Common Workflows

Register and Version

Deploy Pipeline

Rollback

Discovery

Tips

Aliases

Auto-Completion

Scripting

Next Steps