Skip to main content
Product: Edgit Version: v1.0.0 Last Updated: 2025-11-01

​
Overview

This guide walks you through installing Edgit, initializing your repository, and creating your first versioned component. You’ll learn the core workflow in about 5 minutes.

​
Prerequisites

  • Node.js v18 or higher
  • Git v2.30 or higher
  • An existing Git repository (or create one)
  • Basic familiarity with command line

​
Installation

1

Install Edgit CLI globally

npm install -g @ensemble/edgit
Verify installation:
edgit --version
# Output: edgit v1.0.0
2

Navigate to your Git repository

cd /path/to/your/project
git status  # Verify you're in a Git repo
Don’t have a repository? Create one:
mkdir my-project && cd my-project
git init
3

Initialize Edgit

edgit init
This creates .edgit/components.json to track your components:
{
  "version": "1.0",
  "components": {
    "functions": {},
    "agents": {},
    "configs": {}
  }
}

​
Add Your First Component

1

Create a component file

Create src/hello.ts:
export function hello(name: string): string {
  return `Hello, ${name}!`;
}
2

Register the component

edgit add function hello src/hello.ts \
  --description "Simple greeting function"
This updates .edgit/components.json:
{
  "version": "1.0",
  "components": {
    "functions": {
      "hello": {
        "type": "function",
        "path": "src/hello.ts",
        "description": "Simple greeting function"
      }
    }
  }
}
3

Commit your changes

git add src/hello.ts .edgit/
edgit commit  # AI will generate a commit message
Or provide your own message:
edgit commit -m "feat: add hello function"

​
Create Your First Version

1

Create a version tag

edgit tag hello v1.0.0
This creates a Git tag: hello-v1.0.0
2

Push to remote

git push origin hello-v1.0.0
Or push all tags:
git push --tags
3

View component history

edgit components show hello
Output:
Component: hello (function)
Path: src/hello.ts
Description: Simple greeting function

Versions:
  v1.0.0 (2025-11-01 10:30:00) - feat: add hello function

​
Deploy to an Environment

1

Mark version as deployed

edgit deploy hello v1.0.0 --to production
This adds deployment metadata to the Git tag.
2

Check deployment status

edgit status hello
Output:
Component: hello (function)
Latest version: v1.0.0

Deployments:
  production: v1.0.0 (deployed 2025-11-01 10:35:00)

​
Core Commands

# Add components
edgit add function <name> <path>
edgit add agent <name> <path>
edgit add config <name> <path>

# List all components
edgit components list

# Show component details
edgit components show <name>

# Remove component
edgit components remove <name>

# Create version tag
edgit tag <component> <version>

# List versions
edgit tag list <component>

# Delete tag (local and remote)
edgit tag delete <component> <version>

# AI-generated message
edgit commit

# Manual message
edgit commit -m "your message"

# All standard git commit flags work
edgit commit -a -m "message"
edgit commit --amend

# Mark as deployed
edgit deploy <component> <version> --to <environment>

# View deployment status
edgit status <component>

# View all deployments
edgit deploy list

​
Example Workflow

Here’s a complete workflow from development to production: 
# 1. Create and register component
echo "export const api = () => fetch('/api')" > src/api.ts
edgit add function api src/api.ts --description "API client"

# 2. Stage and commit
git add src/api.ts .edgit/
edgit commit  # AI generates: "feat: add API client function"

# 3. Tag development version
edgit tag api v0.1.0
git push origin api-v0.1.0

# 4. Deploy to staging
edgit deploy api v0.1.0 --to staging

# 5. Test in staging...
# 6. Tag production version
edgit tag api v1.0.0
git push origin api-v1.0.0

# 7. Deploy to production
edgit deploy api v1.0.0 --to production

# 8. Check status
edgit status api
# Output:
# staging: v0.1.0
# production: v1.0.0

​
Next Steps

Configuration

Configure AI providers, component types, and defaults

Component Types

Functions, agents, configs, and custom types

CLI Reference

Complete command documentation

Examples

Real-world usage patterns

​
Common Issues

Problem: Running commands in non-initialized repositorySolution: Run edgit init first
edgit init
git add .edgit/
git commit -m "chore: initialize edgit"
Problem: Running edgit outside a Git repositorySolution: Initialize Git first
git init
git add .
git commit -m "Initial commit"
edgit init
Problem: OPENAI_API_KEY not configuredSolution: Set environment variable
export OPENAI_API_KEY=sk-...
Or create .env file:
OPENAI_API_KEY=sk-...