Skip to main content

​
CLI Commands

Quick reference for all Edgit commands.

​
Global

​
edgit --version

Show Edgit version: 
edgit --version
# Output: edgit v0.3.0

​
edgit --help

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

​
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

Register a component: 
edgit components add <type> <name> <path> [options]
Arguments:
  • type - Component type (prompt, config, query, script, agent)
  • name - Unique component name
  • path - File path relative to repo root
Options:
  • --description - Human-readable description
  • --type=agent - Register as agent (for agent implementations)
Examples: 
# Register prompt
edgit components add prompt extraction-prompt 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 agent
edgit components add agent scraper agents/scraper/ --type=agent

​
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 (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

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

# Filter by type
edgit components list --type prompt

# 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

​
edgit tag create

Create a version tag: 
edgit tag create <name> <version> [options]
Arguments:
  • name - Component or agent name
  • version - Semantic version (v..)
Options:
  • --type=agent - Tag an agent (default: component)
  • -m <message> - Tag message
  • --force - Overwrite existing tag
Examples: 
# Version a component
edgit tag create extraction-prompt v1.0.0

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

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

# Force overwrite
edgit tag create extraction-prompt v1.0.0 --force

​
edgit tag list

List versions of a component or agent: 
edgit tag list <name> [options]
Options:
  • --with-dates - Include creation dates
Examples: 
# List versions
edgit tag list extraction-prompt
# Output:
# v1.0.0
# v1.0.1
# v1.1.0

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

​
edgit tag delete

Delete a version tag: 
edgit tag delete <name> <version>
Caution: This deletes the Git tag. Use sparingly.

​
Deployment

​
edgit deploy set

Deploy a version to an environment: 
edgit deploy set <name> <version> --to <environment> [options]
Arguments:
  • name - Component or agent name
  • version - Version to deploy
  • --to - Target environment (prod, staging, dev, etc.)
Options:
  • --type=agent - Deploy an agent
Examples: 
# Deploy to staging
edgit deploy set extraction-prompt v1.0.0 --to staging

# Deploy to production
edgit deploy set extraction-prompt v1.0.0 --to prod

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

# Deploy to custom environment
edgit deploy set extraction-prompt v1.0.0 --to canary

​
edgit deploy get

Get deployed version for an environment: 
edgit deploy get <name> --from <environment>
Examples: 
# Get production version
edgit deploy get extraction-prompt --from prod
# Output: v1.0.0

# Get staging version
edgit deploy get extraction-prompt --from staging
# Output: v0.9.0

​
Discovery

​
edgit discover scan

Scan repository for components: 
edgit discover scan [options]
Options:
  • --type <type> - Filter by type (prompt, config, query, script)
  • --register - Automatically register discovered components
Examples: 
# Scan for all components
edgit discover scan
# Output:
# Found 12 components:
# - components/prompts/extraction.md (prompt)
# - components/configs/api.json (config)
# ...

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

# Scan and register
edgit discover scan --register

​
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

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

​
History

​
edgit history

View deployment history: 
edgit history [name] [options]
Options:
  • --date <ISO8601> - Show versions at specific date/time
  • --from <environment> - Filter by environment
  • --format <type> - Output format (text, json)
Examples: 
# Component history
edgit history extraction-prompt
# Output:
# prod: v1.0.0 (deployed 2024-11-01 14:30)
# staging: v0.9.0 (deployed 2024-10-28 10:15)

# All components at specific time
edgit history --date="2024-11-05T14:47:00Z"
# Output:
# extraction-prompt: v1.0.5
# analysis-prompt: v1.9.2
# validation-config: v1.4.0

# JSON format
edgit history extraction-prompt --format json

​
Git Pass-Through

All git commands work with edgit: 
# Standard git commands
edgit add .
edgit commit -m "message"
edgit push
edgit pull
edgit checkout -b feature
edgit merge main
edgit status
edgit log
edgit diff

# Edgit passes through to git

​
Version Helpers

​
edgit version bump

Calculate next version: 
edgit version bump <version> <level>
Arguments:
  • version - Current version (v1.2.3)
  • level - Bump level (major, minor, patch)
Examples: 
edgit version bump v1.2.3 patch
# Output: v1.2.4

edgit version bump v1.2.3 minor
# Output: v1.3.0

edgit version bump v1.2.3 major
# Output: v2.0.0

​
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 my-prompt components/prompts/my-prompt.md

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

# 3. Push tag
git push --tags

​
Deploy Pipeline

# 1. Deploy to staging
edgit deploy set my-prompt v1.0.0 --to staging
git push --tags

# 2. Test in staging...

# 3. Promote to production
edgit deploy set my-prompt v1.0.0 --to prod
git push --tags

​
Rollback

# 1. Check history
edgit history my-prompt

# 2. Rollback to previous
edgit deploy set my-prompt v0.9.0 --to prod
git push --tags

​
Discovery

# 1. Scan for components
edgit discover scan

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

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

​
Tips

​
Aliases

Add to your .bashrc or .zshrc: 
alias e='edgit'
alias ec='edgit commit'
alias ep='edgit push'
alias et='edgit tag create'
alias ed='edgit deploy 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

Basic Usage

Essential commands and workflows

Versioning Guide

Master versioning strategies

Deployment Strategies

Progressive rollouts and canaries

CI/CD Integration

Automate in your pipeline