First-Time Setup Check

When this skill is activated, ALWAYS run this check first:

bash

cg --version

•If command succeeds: ComfyGit is installed. Proceed with the user's request.
•If command fails ("command not found"): Guide installation before proceeding:

bash

# Install with uv (recommended)
uv tool install comfygit

# Or with pip
pip install comfygit

After installation, verify with cg --version, then help initialize:

bash

cg init                    # Initialize workspace (defaults to ~/comfygit)
cg create <env-name>       # Create first environment

ComfyGit CLI Reference

ComfyGit manages ComfyUI environments with git-based version control, automatic dependency resolution, and portable workflows.

Quick Reference

Essential Commands

bash

# Workspace setup
cg init                              # Initialize workspace at ~/comfygit
cg create myenv                      # Create new environment
cg list                              # List all environments
cg -e myenv run                      # Run ComfyUI in environment

# Node management
cg -e myenv node add <id>            # Add custom node from registry
cg -e myenv node add <github-url>    # Add from GitHub URL
cg -e myenv node remove <name>       # Remove custom node
cg -e myenv node list                # List installed nodes

# Workflow sync (auto-installs dependencies)
cg -e myenv sync                     # Sync all workflows
cg -e myenv workflow resolve <name>  # Resolve specific workflow

# Model management
cg model download <url>              # Download model (CivitAI/HuggingFace/URL)
cg model index sync                  # Scan and index models

# Git operations
cg -e myenv status                   # Show environment status
cg -e myenv commit -m "message"      # Commit changes
cg -e myenv pull                     # Pull and repair environment

# Environment config
cg -e myenv env-config torch-backend set cu121  # Set PyTorch backend

Global Flag

•-e <name> or --env <name>: Target specific environment (required for most operations)
•Without -e: Uses active environment (set via cg use <name>)

Architecture Overview

code

Workspace (~/comfygit/)
├── environments/<name>/
│   ├── .cec/                    # Git-tracked config
│   │   ├── pyproject.toml       # Dependencies & node tracking
│   │   ├── workflows/           # Workflow JSON files
│   │   └── .git/                # Environment version control
│   └── ComfyUI/                 # ComfyUI installation
│       ├── custom_nodes/ → symlink
│       └── models/ → symlink
├── models/                      # Global model storage
└── comfygit_cache/              # Registry data, model index

Key Design:

•Each environment is independently versioned via git
•Models stored globally (symlinked into environments)
•PyTorch backend is machine-specific (not in git)
•Workflows auto-sync dependencies on cg run

Command Categories

Environment Commands (require `-e <name>` or active environment)

Command	Purpose
`run`	Launch ComfyUI (syncs first unless `--no-sync`)
`sync`	Install/update all dependencies
`status`	Show workflow status, missing nodes, git status
`repair`	Restore environment to pyproject.toml state

Node Commands

Command	Purpose
`node add <id>`	Install from registry (e.g., `comfyui-manager`)
`node add <url>`	Install from GitHub URL
`node add <path> --dev`	Track local development node
`node remove <name>`	Remove node (keeps dev nodes on disk)
`node update <name>`	Update to latest version
`node list`	Show installed nodes
`node prune`	Remove unused nodes

Node identifiers:

•Registry ID: comfyui-manager, comfyui-manager@1.2.3
•GitHub URL: https://github.com/user/repo
•GitHub with ref: https://github.com/user/repo@branch

Workflow Commands

Command	Purpose
`workflow list`	Show all workflows with sync status
`workflow resolve <name>`	Resolve single workflow dependencies
`workflow resolve <name> --install`	Resolve and auto-install

Workflow sync status:

•synced - Dependencies resolved and installed
•modified - Workflow changed, needs re-sync
•new - Not yet resolved
•issues - Missing nodes or models

Model Commands

Command	Purpose
`model download <url>`	Download from CivitAI/HuggingFace/URL
`model add-source <model> <url>`	Add download source to existing model
`model index sync`	Scan and index all models
`model index find <query>`	Search models by name/hash

Supported sources:

•CivitAI: https://civitai.com/api/download/models/123456
•HuggingFace: https://huggingface.co/org/model/resolve/main/file.safetensors
•Direct URLs: Any direct download link

Git Commands

Command	Purpose
`log`	Show commit history
`commit -m "msg"`	Save environment changes
`checkout <ref>`	Checkout commit/branch
`branch`	List/create/delete branches
`switch <branch>`	Switch branch
`pull`	Pull and repair environment
`push`	Push commits to remote

Python Dependency Commands

Command	Purpose
`py add <pkg>`	Add Python dependency
`py add <pkg> --dev`	Add dev dependency
`py remove <pkg>`	Remove dependency
`py list`	List all dependencies
`py uv <args>`	Direct UV passthrough
`constraint add <pkg>`	Add version constraint

Common Workflows

Starting Fresh

bash

cg init                           # Initialize workspace
cg create production              # Create environment
cg -e production run              # Launch ComfyUI

Installing Custom Nodes

bash

# From registry (preferred)
cg -e myenv node add comfyui-manager

# From GitHub (specific version)
cg -e myenv node add https://github.com/user/repo@v1.0.0

# Development mode (local source)
cg -e myenv node add /path/to/node --dev

Syncing Shared Workflows

bash

# Put workflow.json in ComfyUI/user/default/workflows/
cg -e myenv workflow resolve my_workflow.json --install
# Interactive prompts for unknown nodes/models

Exporting/Importing Environments

bash

# Export (creates portable tarball)
cg -e production export ./production.tar.gz

# Import from tarball
cg import ./production.tar.gz --name imported

# Import from git repository
cg import https://github.com/user/comfygit-env --name from-git

Handling Conflicts

When cg node add fails with conflicts:

•Duplicate node: Remove existing first or use --force
•Dependency conflict: Add constraint or use --no-test
•Git conflict: Check suggested actions in error output

bash

# See full error
cg -e myenv node add <pkg> --verbose

# Force installation (skip dependency test)
cg -e myenv node add <pkg> --no-test

# Add version constraint
cg -e myenv constraint add "package==1.2.3"

Error Handling

Node Conflict Errors

Error format includes suggested actions:

code

✗ Node conflict: <name>
  Filesystem: <url>
  Registry:   <url>

Suggested actions:
  1. Remove conflicting node
     → cg node remove <name>
  2. Track as dev node
     → cg node add <name> --dev

Dependency Conflict Errors

code

✗ Dependency conflict installing <node>

  • package-a requires X>=2.0
  • package-b requires X<1.5

Options:
  1. Remove conflicting node
     → cg node remove <other-node>
  2. Add version constraint
     → cg constraint add "X==1.4.9"

Reference Documents

For detailed information on specific subsystems:

•CLI Commands Reference - Complete command reference with all flags
•Core Architecture - Library internals and data flow
•Workflow Resolution - Node and model resolution strategies
•Configuration Files - pyproject.toml, package_config.toml structure

First-Time Setup Check

ComfyGit CLI Reference

Quick Reference

Essential Commands

Global Flag

Architecture Overview

Command Categories

Environment Commands (require -e <name> or active environment)

Node Commands

Workflow Commands

Model Commands

Git Commands

Python Dependency Commands

Common Workflows

Starting Fresh

Installing Custom Nodes

Syncing Shared Workflows

Exporting/Importing Environments

Handling Conflicts

Error Handling

Node Conflict Errors

Dependency Conflict Errors

Reference Documents

Environment Commands (require `-e <name>` or active environment)