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

> Complete Edgit command reference with examples

## Getting Started

No installation needed - use `npx` to run Edgit:

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

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

## Global

### `edgit --version`

Show Edgit version:

```bash theme={null}
edgit --version
# Output: edgit v0.4.4
```

<Tip>
  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](/introduction/ensemble-cli#checking-for-updates-landscape-view) for details.
</Tip>

### `edgit --help`

Show help:

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

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

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

```
📦 Edgit Info

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

**Example Output (JSON):**

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

```json theme={null}
{
  "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"
    }
  ]
}
```

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

### `edgit info` (Direct CLI)

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

```bash theme={null}
npx @ensemble-edge/edgit info [options]
# or
edgit info [options]
```

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

## Initialization

### `edgit init`

Initialize Edgit in your repository:

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

Creates:

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

**Requirements:** Must be in a Git repository

## Component Registry

### `edgit components add`

Register a component:

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

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

```bash theme={null}
edgit components list [options]
```

**Options:**

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

**Examples:**

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

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

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

```bash theme={null}
edgit tag create <name> <version> [options]
```

**Arguments:**

* `name` - Component name
* `version` - Semantic version (v{major}.{minor}.{patch})

**Options:**

* `-m <message>` - Tag message

**Examples:**

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

<Note>
  Version tags are immutable and don't require `--force` to push.
</Note>

### `edgit tag bump`

Bump the version of a component based on semantic versioning:

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

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

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

### `edgit tag set`

Create or move a mutable environment tag:

```bash theme={null}
edgit tag set <component> <environment> [ref]
```

**Arguments:**

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

**Examples:**

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

<Note>
  Environment tags are mutable and require `--force` when pushing if the tag has moved: `edgit push --tags --force`
</Note>

### `edgit tag list`

List versions of a component:

```bash theme={null}
edgit tag list <name> [options]
```

**Options:**

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

**Examples:**

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

```bash theme={null}
edgit tag show <name>@<version> [options]
```

**Options:**

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

**Examples:**

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

```bash theme={null}
edgit tag delete <name> <version>
```

**Caution:** This deletes the Git tag. Use sparingly.

## Push

### `edgit push`

Push commits and tags to remote:

```bash theme={null}
edgit push                    # Push commits only
edgit push --tags             # Push commits + all tags
edgit push --tags --force     # Push with force (for moved environment tags)
```

**Examples:**

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

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

## Discovery

### `edgit discover scan`

Scan repository for components:

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

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

```bash theme={null}
edgit discover detect <file>
```

**Examples:**

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

```bash theme={null}
edgit discover patterns list [options]
```

**Options:**

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

**Examples:**

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

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

<Note>
  For standard git operations, you can also use `git` directly. The pass-through is convenient when you're already working with edgit commands.
</Note>

## Version Management

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

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

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

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

## Environment Variables

Edgit respects these environment variables:

### `OPENAI_API_KEY`

OpenAI API key for AI-powered commit messages:

```bash theme={null}
export OPENAI_API_KEY=sk-...
edgit commit  # AI generates message
```

### `EDGIT_REGISTRY_PATH`

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

```bash theme={null}
export EDGIT_REGISTRY_PATH=.custom/registry.json
```

### `EDGIT_AUTO_PUSH`

Automatically push tags after creating them:

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

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

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

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

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

```bash theme={null}
alias edgit='npx @ensemble-edge/edgit'
alias et='edgit tag create'
alias ed='edgit tag set'
```

### Auto-Completion

Generate completion script:

```bash theme={null}
edgit completion bash > /etc/bash_completion.d/edgit  # Bash
edgit completion zsh > ~/.zsh/completion/_edgit       # Zsh
```

### Scripting

Use `--format json` for scripts:

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

## Next Steps

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

  <Card title="Basic Usage" icon="rocket" href="/edgit/getting-started/basic-usage">
    Essential commands and workflows
  </Card>

  <Card title="Versioning Guide" icon="tags" href="/edgit/guides/versioning-components-agents">
    Master versioning strategies
  </Card>

  <Card title="CI/CD Integration" icon="workflow" href="/edgit/getting-started/cicd-integration">
    Automate in your pipeline
  </Card>
</CardGroup>