> ## 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. # Basic Usage > The 5 Edgit commands you'll use 95% of the time: version, deploy, rollback ## The Workflow ```bash theme={null} # 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. Push tags edgit push --tags # 4. Deploy to staging edgit tag set my-prompt staging v1.0.0 edgit push --tags --force # 5. Check status edgit components list ``` That's it. Everything else is details. **Philosophy:** Edgit's job ends at `git push`. GitHub Actions handles deployment. ## Register Components Tell Edgit what files are components: ```bash theme={null} # 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:** ```bash theme={null} # 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{major}.{minor}.{patch}): ```bash theme={null} # 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/prompts/my-prompt/v1.0.0 ``` **Version multiple components:** ```bash theme={null} 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. **Tags use 4-level format:** * `components/prompts/my-prompt/v1.0.0` (version tag) * `components/prompts/my-prompt/staging` (environment tag) The prefix (`components/prompts/`) is automatically inferred from the component type. ## Deploy to Environment Mark which versions are deployed to which environments: ```bash theme={null} # Deploy to staging edgit tag set my-prompt staging v1.0.0 edgit push --tags --force # Test in staging... # All good? Deploy to production edgit tag set my-prompt prod v1.0.0 edgit push --tags --force # Deploy multiple components edgit tag set extraction-prompt prod v1.0.0 edgit tag set analysis-config prod v2.1.0 edgit push --tags --force ``` **Deployment is just metadata.** Edgit creates tags like `components/prompts/my-prompt/prod` that point to `v1.0.0`. Your CI/CD reads these tags. ## When to Use --force * **Version tags:** No `--force` needed. These are permanent markers. ```bash theme={null} edgit tag create my-prompt v1.0.0 edgit push --tags ``` * **Environment tags:** `--force` required when moving environments. ```bash theme={null} edgit tag set my-prompt prod v1.0.0 edgit push --tags --force ``` ## Check Status See what's deployed where: ```bash theme={null} # 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: ```bash theme={null} # Rollback to previous version edgit tag set my-prompt prod v0.9.0 edgit push --tags --force # Or specific version edgit tag set my-prompt prod v0.5.0 edgit push --tags --force ``` **Rollback is instant** (\<50ms globally if you've deployed version data to Cloudflare KV). ## View Versions See component versions and details: ```bash theme={null} # List all versions edgit tag list my-prompt # Output: v1.0.0, v0.9.0, v0.8.0 # Show version details edgit tag show my-prompt@v1.0.0 # Shows: commit, author, date, changes ``` ## Version Agents Too Agents can be versioned just like components: ```bash theme={null} # Register an agent edgit components add agent scraper agents/scraper/ # Version it edgit tag create scraper v1.5.0 # Deploy it edgit tag set scraper prod v1.5.0 edgit push --tags --force # Now reference in ensembles ``` ```yaml theme={null} agents: - name: scraper agent: scraper@v1.5.0 # Locked to specific version ``` ## Common Patterns ### Progressive Rollout ```bash theme={null} # Deploy to staging first edgit tag set my-prompt staging v2.0.0 edgit push --tags --force # Test thoroughly... # Deploy to canary (10% of prod traffic) edgit tag set my-prompt canary v2.0.0 edgit push --tags --force # Monitor... # Full prod rollout edgit tag set my-prompt prod v2.0.0 edgit push --tags --force ``` ### A/B Testing ```bash theme={null} # Deploy variant A edgit tag set my-prompt prod-variant-a v1.0.0 edgit push --tags --force # Deploy variant B edgit tag set my-prompt prod-variant-b v2.0.0 edgit push --tags --force # Your ensemble references both ``` ```yaml theme={null} 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 ```bash theme={null} # Production is broken! # Check available versions edgit tag list my-prompt # Rollback to last known good edgit tag set my-prompt prod v0.9.5 edgit push --tags --force # Under 50ms later, you're back to working version ``` ## Use Edgit for All Git Operations Remember: **Edgit is 100% Git-compatible.** ```bash theme={null} # 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 ```bash theme={null} # Register edgit components add # Version edgit tag create edgit tag list edgit tag show @ # Deploy edgit tag set edgit push --tags --force # Status edgit components list edgit components list --format tree|table|json # Discover edgit discover scan edgit discover scan --type prompt|config|query|script edgit discover detect # Standard git (all work with edgit) edgit add|commit|push|pull|checkout|merge|... ``` ## Next Steps Deep dive into versioning strategies Progressive rollouts, A/B testing, canaries Automate versioning in your pipeline Complete command documentation