Skip to main content

​
Basic Usage

The 5 commands you’ll use 95% of the time.

​
The Workflow

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

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

# 3. Deploy it
edgit deploy set my-prompt v1.0.0 --to prod

# 4. Need to rollback?
edgit deploy set my-prompt v0.9.0 --to prod

# 5. Check status
edgit components list --format tree
That’s it. Everything else is details.

​
Register Components

Tell Edgit what files are components: 
# Register a prompt
edgit components add prompt extraction-prompt components/prompts/extraction.md

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

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

# Register a script
edgit components add script transform components/scripts/transform.ts
Or discover automatically: 
# Scan for all components
edgit discover scan

# Detect a specific file
edgit discover detect src/my-function.ts
# Output: Type: script, Confidence: 95%

​
Create Versions

Use semantic versioning (v..): 
# Create version tag
edgit tag create my-prompt v1.0.0

# List versions
edgit tag list my-prompt
# Output: v1.0.0, v1.1.0, v1.2.0

# View what changed
git show components/my-prompt/v1.0.0
Version multiple components: 
edgit tag create extraction-prompt v1.0.0
edgit tag create analysis-config v2.1.0
edgit tag create validation-query v0.5.0
Each component gets its own independent version history.

​
Deploy Versions

Mark which versions are deployed to which environments: 
# Deploy to staging
edgit deploy set my-prompt v1.0.0 --to staging

# Test in staging...
# All good? Deploy to production
edgit deploy set my-prompt v1.0.0 --to prod

# Deploy multiple components
edgit deploy set extraction-prompt v1.0.0 --to prod
edgit deploy set analysis-config v2.1.0 --to prod
Deployment is just metadata. Edgit creates tags like components/my-prompt/prod that point to v1.0.0. Your CI/CD reads these tags.

​
Check Status

See what’s deployed where: 
# Tree view
edgit components list --format tree
# Output:
# extraction-prompt (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 prompt  v1.0.0   v1.0.0   v0.9.0
# analysis-config   config  v2.1.0   v2.1.0   v2.0.0

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

​
Rollback

Something broke? Rollback instantly: 
# Rollback to previous version
edgit deploy set my-prompt v0.9.0 --to prod

# Or specific version
edgit deploy set my-prompt v0.5.0 --to prod
Rollback is instant (<50ms globally if you’ve deployed version data to Cloudflare KV).

​
View History

See deployment history: 
# Component history
edgit history my-prompt
# Output:
# prod: v1.0.0 (deployed 2025-11-01 14:30)
# staging: v0.9.0 (deployed 2025-10-28 10:15)

# What was deployed on a specific date?
edgit history --date="2024-11-05T14:47:00Z"
# Output shows exact versions deployed at that time

​
Version Agents Too

Agents can be versioned just like components: 
# Register an agent
edgit components add agent scraper agents/scraper/ --type=agent

# Version it
edgit tag create scraper v1.5.0 --type=agent

# Deploy it
edgit deploy set scraper v1.5.0 --to prod --type=agent

# Now reference in ensembles

agents:
  - name: scraper
    agent: scraper@v1.5.0  # Locked to specific version

​
Common Patterns

​
Progressive Rollout

# Deploy to staging first
edgit deploy set my-prompt v2.0.0 --to staging

# Test thoroughly...

# Deploy to canary (10% of prod traffic)
edgit deploy set my-prompt v2.0.0 --to canary

# Monitor...

# Full prod rollout
edgit deploy set my-prompt v2.0.0 --to prod

​
A/B Testing

# Deploy variant A
edgit deploy set my-prompt v1.0.0 --to prod-variant-a

# Deploy variant B
edgit deploy set my-prompt v2.0.0 --to prod-variant-b

# Your ensemble references both

agents:
  - name: analyzer-a
    operation: think
    component: my-prompt@v1.0.0

  - name: analyzer-b
    operation: think
    component: my-prompt@v2.0.0

​
Emergency Rollback

# Production is broken!
# Check what was deployed before
edgit history my-prompt

# Rollback to last known good
edgit deploy set my-prompt v0.9.5 --to prod

# &lt;50ms later, you're back to working version

​
Use Edgit for All Git Operations

Remember: Edgit is 100% Git-compatible. 
# Use edgit for everything
edgit add .
edgit commit  # AI-powered if OPENAI_API_KEY is set
edgit push
edgit pull
edgit checkout -b feature/new-prompt
edgit merge main

# All git commands work

​
Cheat Sheet

# Register
edgit components add <type> <name> <path>

# Version
edgit tag create <name> <version>
edgit tag list <name>

# Deploy
edgit deploy set <name> <version> --to <env>
edgit deploy get <name> --from <env>

# Status
edgit components list
edgit components list --format tree|table|json
edgit history <name>
edgit history --date="2024-11-05T14:47:00Z"

# Discover
edgit discover scan
edgit discover scan --type prompt|config|query|script
edgit discover detect <file>

# Standard git (all work with edgit)
edgit add|commit|push|pull|checkout|merge|...

​
Next Steps

Versioning Guide

Deep dive into versioning strategies

Deployment Strategies

Progressive rollouts, A/B testing, canaries

CI/CD Integration

Automate versioning in your pipeline

CLI Reference

Complete command documentation