CLI Reference

Product: Edgit Version: v1.0.0 Last Updated: 2025-11-01

Global Commands

`edgit --version`

Display the current version of Edgit.

edgit --version
# Output: edgit v1.0.0

`edgit --help`

Show general help information.

edgit --help

Initialization

`edgit init`

Initialize Edgit in a Git repository.

edgit init

What it does:

Creates .edgit/ directory
Creates components.json registry
Sets up initial structure

Requirements:

Must be in a Git repository
Must have write permissions

Example:

cd my-project
git init
edgit init
# Output: ✅ Edgit initialized in /path/to/my-project

Component Management

`edgit add <type> <name> <path>`

edgit add <type> <name> <path> [options]

type

string

required

Component type (function, agent, config, or custom)

name

string

required

Unique component name (alphanumeric, hyphens, underscores)

path

string

required

Relative path from repository root

--description

string

Human-readable description

--metadata

json

Custom metadata as JSON string

Examples:

# Add function
edgit add function email-processor src/functions/email.ts \
  --description "Processes incoming emails"

# Add agent with metadata
edgit add agent support-bot src/agents/support.ts \
  --description "Customer support automation" \
  --metadata '{"model":"gpt-4","temperature":0.7}'

# Add config
edgit add config app-settings config/app.json

# Add custom type
edgit add workflow order-flow workflows/order.yaml

`edgit components list`

List all registered components.

edgit components list [options]

--type

string

Filter by component type

--format

string

default:"table"

Output format: table, json, yaml

Examples:

# List all components
edgit components list

# List only functions
edgit components list --type function

# JSON output
edgit components list --format json

Output:

Type      Name              Path                          Description
function  email-processor   src/functions/email.ts        Processes incoming emails
agent     support-bot       src/agents/support.ts         Customer support automation
config    app-settings      config/app.json               Application settings

`edgit components show <name>`

Show detailed information about a component.

edgit components show <name> [options]

name

string

required

Component name

--versions

boolean

Include version history

--deployments

boolean

Include deployment history

Example:

edgit components show email-processor --versions --deployments

Output:

Component: email-processor (function)
Path: src/functions/email.ts
Description: Processes incoming emails

Versions:
  v1.2.0 (2025-11-01) - feat: add retry logic
  v1.1.0 (2025-10-15) - feat: add error handling
  v1.0.0 (2025-10-01) - Initial release

Deployments:
  production: v1.2.0 (deployed 2025-11-01 14:30:00)
  staging: v1.2.0 (deployed 2025-11-01 10:00:00)

Dependencies:
  - queue-manager (v2.0.0)
  - logger (v1.5.0)

`edgit components remove <name>`

Remove a component from the registry.

edgit components remove <name> [options]

name

string

required

Component name

--force

boolean

Skip confirmation prompt

--delete-tags

boolean

Also delete all Git tags for this component

Example:

# With confirmation
edgit components remove old-function

# Force removal
edgit components remove old-function --force

# Remove component and all tags
edgit components remove old-function --force --delete-tags

Versioning

`edgit tag <component> <version>`

Create a version tag for a component.

edgit tag <component> <version> [options]

component

string

required

Component name

version

string

required

Semantic version (vX.Y.Z format)

--message

string

Tag annotation message

--force

boolean

Overwrite existing tag (dangerous!)

Examples:

# Create version tag
edgit tag email-processor v1.0.0

# With custom message
edgit tag email-processor v1.0.0 --message "Stable release"

# Overwrite existing (not recommended)
edgit tag email-processor v1.0.0 --force

What it does:

Creates Git tag: <component>-v<version>
Annotates with commit message
Records in component history

List all version tags for a component.

edgit tag list <component> [options]

component

string

required

Component name

--format

string

default:"table"

Output format: table, json, list

Example:

edgit tag list email-processor

Output:

Version   Date                 Commit
v1.2.0    2025-11-01 10:00     abc1234 feat: add retry logic
v1.1.0    2025-10-15 14:30     def5678 feat: error handling
v1.0.0    2025-10-01 09:00     ghi9012 Initial release

`edgit tag delete <component> <version>`

Delete a version tag.

edgit tag delete <component> <version> [options]

component

string

required

Component name

version

string

required

Version to delete

--remote

boolean

Also delete from remote repository

Example:

# Delete local tag
edgit tag delete email-processor v1.0.0

# Delete local and remote
edgit tag delete email-processor v1.0.0 --remote

Warning: Deleting published tags is not recommended.

Commits

`edgit commit`

Commit with AI-powered message generation or pass through to git.

edgit commit [git-options]

All standard git commit options are supported:

-m, --message

string

Manual commit message (disables AI)

-a, --all

boolean

Stage all modified files

--amend

boolean

Amend previous commit

Examples:

# AI-generated message
git add src/email.ts
edgit commit
# Output: ✅ Committed: "feat(email-processor): add retry logic"

# Manual message
edgit commit -m "fix: update email validation"

# Stage all and commit with AI
edgit commit -a

# Amend with AI message
edgit commit --amend --no-edit

AI Behavior:

Analyzes staged file changes
Detects changed components
Generates conventional commit format
Falls back to git commit if AI unavailable
Uses existing message if -m provided

Deployment

`edgit deploy <component> <version>`

Mark a component version as deployed to an environment.

edgit deploy <component> <version> --to <environment> [options]

component

string

required

Component name

version

string

required

Version to deploy (must exist as tag)

--to

string

required

Target environment name

--metadata

json

Custom deployment metadata

Examples:

# Mark as deployed
edgit deploy email-processor v1.2.0 --to production

# With metadata
edgit deploy email-processor v1.2.0 --to production \
  --metadata '{"deployer":"john","ticket":"PROJ-123"}'

What it does:

Verifies version tag exists
Records deployment metadata
Updates component deployment history

`edgit deploy list [component]`

List deployment history.

edgit deploy list [component] [options]

component

string

Filter by component (optional)

--environment

string

Filter by environment

Examples:

# All deployments
edgit deploy list

# For specific component
edgit deploy list email-processor

# For specific environment
edgit deploy list --environment production

`edgit status <component>`

Show current deployment status for a component.

edgit status <component>

component

string

required

Component name

Example:

edgit status email-processor

Output:

Component: email-processor (function)
Latest version: v1.2.0

Deployments:
  development: v1.3.0-beta (deployed 2025-11-01 16:00:00)
  staging: v1.2.0 (deployed 2025-11-01 10:00:00)
  production: v1.2.0 (deployed 2025-11-01 14:30:00)

Global Options

These options work with all commands:

--help, -h

boolean

Show help for any command

edgit add --help
edgit tag --help

--version, -v

boolean

Show version information

edgit --version

--debug

boolean

Enable debug output

edgit --debug commit

--quiet, -q

boolean

Suppress non-error output

edgit --quiet components list

Exit Codes

Edgit uses standard exit codes:

Code	Meaning
0	Success
1	General error
2	Usage error (invalid arguments)
3	Not a Git repository
4	Not initialized (run `edgit init`)
5	Component not found
6	Version already exists
7	AI error (API key invalid or service unavailable)

Environment Variables

See Configuration for complete environment variable documentation. Quick reference:

OPENAI_API_KEY=sk-...      # Required for AI features
EDGIT_DEBUG=true           # Enable debug mode
EDGIT_DIR=.edgit           # Custom directory name

Examples

Complete Workflow

# 1. Initialize
git init
edgit init

# 2. Add component
edgit add function api src/api.ts --description "API handler"

# 3. Commit changes
git add .
edgit commit  # AI: "feat(api): add API handler function"

# 4. Create version
edgit tag api v1.0.0

# 5. Push to remote
git push origin main --tags

# 6. Deploy to staging
edgit deploy api v1.0.0 --to staging

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

# 8. Check status
edgit status api

Batch Operations

# Add multiple components
for file in src/functions/*.ts; do
  name=$(basename "$file" .ts)
  edgit add function "$name" "$file"
done

# List all versions for all components
edgit components list --format json | \
  jq -r '.[] | .name' | \
  xargs -I {} edgit tag list {}

# Deploy all to staging
edgit tag list --all | \
  xargs -I {} edgit deploy {} --to staging

Next Steps

Configuration

Environment variables and settings

Examples

Real-world usage patterns

Guides

In-depth feature documentation

Troubleshooting

Common issues and solutions

Edgit

Edgit Guides

Edgit API Reference

Edgit Examples

Global Commands

`edgit --version`

`edgit --help`

Initialization

`edgit init`

Component Management

`edgit add <type> <name> <path>`

`edgit components list`

`edgit components show <name>`

`edgit components remove <name>`

Versioning

`edgit tag <component> <version>`

`edgit tag delete <component> <version>`

Commits

`edgit commit`

Deployment

`edgit deploy <component> <version>`

`edgit deploy list [component]`

`edgit status <component>`

Global Options

Exit Codes

Environment Variables

Examples

Complete Workflow

Batch Operations

Next Steps

Configuration

Examples

Guides

Troubleshooting

Edgit

Edgit Guides

Edgit API Reference

Edgit Examples

​Global Commands

​edgit --version

​edgit --help

​Initialization

​edgit init

​Component Management

​edgit add <type> <name> <path>

​edgit components list

​edgit components show <name>

​edgit components remove <name>

​Versioning

​edgit tag <component> <version>

​edgit tag list <component>

​edgit tag delete <component> <version>

​Commits

​edgit commit

​Deployment

​edgit deploy <component> <version>

​edgit deploy list [component]

​edgit status <component>

​Global Options

​Exit Codes

​Environment Variables

​Examples

​Complete Workflow

​Batch Operations

​Next Steps

Configuration

Examples

Guides

Troubleshooting

Global Commands

`edgit --version`

`edgit --help`

Initialization

`edgit init`

Component Management

`edgit add <type> <name> <path>`

`edgit components list`

`edgit components show <name>`

`edgit components remove <name>`

Versioning

`edgit tag <component> <version>`

`edgit tag list <component>`

`edgit tag delete <component> <version>`

Commits

`edgit commit`

Deployment

`edgit deploy <component> <version>`

`edgit deploy list [component]`

`edgit status <component>`

Global Options

Exit Codes

Environment Variables

Examples

Complete Workflow

Batch Operations

Next Steps