cm-cli-rest & comfy-cli REST

A ComfyUI custom node that exposes REST API endpoints for managing ComfyUI custom nodes and models via cm-cli (ComfyUI-Manager CLI) and comfy-cli.

Features

• 🚀 Dual CLI Support: REST APIs for both cm-cli and comfy-cli
• 🔗 Integrated with ComfyUI: Uses ComfyUI's built-in server (no separate port)
• ⚡ Async Operations: Long-running commands (install, update, download) run asynchronously
• 📊 Job Tracking: Monitor progress of async operations
• 🛡️ Error Handling: Comprehensive error responses with status codes
• 🔐 Optional Authentication: API key support for exposed instances

Installation

Prerequisites

• ComfyUI 0.15+
• ComfyUI-Manager 4.0+ (provides cm-cli)
• Python 3.9+
• comfy-cli (optional, for model management): pip install comfy-cli

Steps

1. Clone this repository into your ComfyUI custom nodes directory:

   cd ComfyUI/custom_nodes
   git clone https://github.com/YOUR_USERNAME/cm-cli-rest.git
   

2. Install comfy-cli (optional, for model management):

   pip install comfy-cli
   

3. Restart ComfyUI

4. Verify installation: Check ComfyUI console for:

   cm-cli-rest & comfy-cli REST initialized - APIs available at /cm-cli-rest/* and /comfy-cli/*
   

Quick Start

Health Check (cm-cli)

curl http://localhost:8188/cm-cli-rest/health

Response:

{
  "status": "healthy",
  "service": "cm-cli-rest",
  "version": "0.1.0",
  "timestamp": "2026-03-15T10:00:00Z"
}

List Installed Nodes (cm-cli)

curl http://localhost:8188/cm-cli-rest/nodes

Install a Node (cm-cli)

curl -X POST http://localhost:8188/cm-cli-rest/nodes/install \
  -H "Content-Type: application/json" \
  -d '{"name": "ComfyUI-Impact-Pack"}'

Response (202 Accepted):

{
  "success": true,
  "data": {
    "job_id": "abc12345",
    "status": "running",
    "message": "Installation started for 'ComfyUI-Impact-Pack'"
  }
}

List Models (comfy-cli)

curl "http://localhost:8188/comfy-cli/model/list?relative_path=models/checkpoints"

Download a Model (comfy-cli)

curl -X POST "http://localhost:8188/comfy-cli/model/download" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://civitai.com/models/43331",
    "relative_path": "models/checkpoints"
  }'

Check Job Status

curl http://localhost:8188/cm-cli-rest/jobs/abc12345

API Endpoints

cm-cli REST API (/cm-cli-rest/*)

Health & Status

Method	Endpoint	Description
GET	/cm-cli-rest/health	Health check
GET	/cm-cli-rest/jobs	List all jobs
GET	/cm-cli-rest/jobs/:id	Get job status
DELETE	/cm-cli-rest/jobs/:id	Remove job from tracking

Node Management

Method	Endpoint	Description	Async
GET	/cm-cli-rest/nodes	List installed nodes	No
GET	/cm-cli-rest/nodes/:name	Get node details	No
POST	/cm-cli-rest/nodes/install	Install node	✅
POST	/cm-cli-rest/nodes/uninstall	Uninstall node	No
POST	/cm-cli-rest/nodes/update	Update node	✅
POST	/cm-cli-rest/nodes/update-all	Update all nodes	✅
POST	/cm-cli-rest/nodes/enable	Enable node	No
POST	/cm-cli-rest/nodes/disable	Disable node	No
POST	/cm-cli-rest/nodes/fix	Fix node dependencies	✅
POST	/cm-cli-rest/nodes/reinstall	Reinstall node	✅

Snapshots

Method	Endpoint	Description	Async
POST	/cm-cli-rest/snapshots/save	Save snapshot	No
POST	/cm-cli-rest/snapshots/restore	Restore snapshot	✅
GET	/cm-cli-rest/snapshots	List snapshots	No

comfy-cli REST API (/comfy-cli/*)

Configuration

Method	Endpoint	Description
GET	/comfy-cli/config/env	Get environment config
GET	/comfy-cli/config/which	Get workspace path
POST	/comfy-cli/config/set-default	Set default workspace

Model Management

Method	Endpoint	Description	Async
GET	/comfy-cli/model/list	List models	No
POST	/comfy-cli/model/download	Download model	✅
GET	/comfy-cli/model/download/:id/status	Get download status	No
POST	/comfy-cli/model/remove	Remove model	No

Node Management

Method	Endpoint	Description	Async
GET	/comfy-cli/node/simple-show	List nodes (simple)	No
GET	/comfy-cli/node/show	List nodes (detailed)	No
POST	/comfy-cli/node/install	Install node	✅
POST	/comfy-cli/node/update	Update node	✅
POST	/comfy-cli/node/enable	Enable node	No
POST	/comfy-cli/node/disable	Disable node	No
POST	/comfy-cli/node/uninstall	Uninstall node	No

Request/Response Examples

cm-cli: Install Node with Options

curl -X POST http://localhost:8188/cm-cli-rest/nodes/install \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ComfyUI-Impact-Pack",
    "channel": "recent",
    "mode": "remote"
  }'

cm-cli: Update All Nodes

curl -X POST http://localhost:8188/cm-cli-rest/nodes/update-all

cm-cli: Save Snapshot

curl -X POST http://localhost:8188/cm-cli-rest/snapshots/save \
  -H "Content-Type: application/json" \
  -d '{"name": "pre-update-backup"}'

comfy-cli: Download Model

curl -X POST "http://localhost:8188/comfy-cli/model/download" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://civitai.com/models/43331",
    "relative_path": "models/checkpoints",
    "filename": "my_model.safetensors"
  }'

comfy-cli: List Installed Nodes

curl "http://localhost:8188/comfy-cli/node/simple-show?mode=installed"

comfy-cli: Install Node

curl -X POST "http://localhost:8188/comfy-cli/node/install" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": ["ComfyUI-Impact-Pack"],
    "fast_deps": true
  }'

Error Responses

All errors follow this format:

{
  "success": false,
  "error": {
    "code": "NODE_NOT_FOUND",
    "message": "Node 'invalid-node' not found",
    "details": "Additional context..."
  }
}

Common Error Codes (cm-cli)

Code	HTTP Status	Description
CM_CLI_NOT_FOUND	500	cm-cli.py not found
NODE_NOT_FOUND	404	Node not in registry
INSTALL_FAILED	500	Installation failed
JOB_NOT_FOUND	404	Job ID not found
TIMEOUT	504	Command timed out
INVALID_REQUEST	400	Malformed request

Common Error Codes (comfy-cli)

Code	HTTP Status	Description
COMFY_CLI_ERROR	500	comfy-cli execution failed
COMMAND_FAILED	500	CLI command returned error
MISSING_PARAMETER	400	Required parameter missing
INVALID_PARAMETER	400	Invalid parameter value
JOB_NOT_FOUND	404	Async job ID not found

Configuration

Edit config/config.json:

{
  "enabled": true,              // Enable/disable API
  "api_key": null,              // Optional API key for auth
  "cm_cli_path": null,          // Auto-detect if null
  "python_path": "python",      // Python interpreter
  "timeout": 300,               // Command timeout (seconds)
  "max_concurrent_jobs": 3,     // Max parallel operations
  "logging_level": "INFO"       // Logging verbosity
}

Architecture

cm-cli-rest/
├── __init__.py              # Entry point, initializes both executors
├── api/
│   ├── routes.py            # cm-cli route definitions
│   └── handlers/
│       ├── nodes.py         # Node management (cm-cli)
│       ├── snapshots.py     # Snapshots (cm-cli)
│       ├── jobs.py          # Job tracking (shared)
│       ├── config.py        # Config (comfy-cli)
│       ├── models.py        # Models (comfy-cli)
│       └── comfy_nodes.py   # Nodes (comfy-cli)
├── cm_cli/
│   └── executor.py          # cm-cli subprocess execution
├── comfy_cli/
│   └── executor.py          # comfy-cli subprocess execution
├── comfy_cli_routes.py      # comfy-cli route registration
├── config/
│   └── config.json          # Configuration file
└── README.md

How It Works

1. Integration: Routes registered with PromptServer.instance.app (ComfyUI's aiohttp server)
2. Execution: Commands executed via asyncio.create_subprocess_exec
3. Job Tracking: Long-running operations tracked in-memory with UUID
4. Error Handling: Comprehensive error responses with appropriate HTTP status codes

Development

Running Tests

# TODO: Add test suite
pytest tests/

Syntax Validation

# Check all Python files
find . -name "*.py" -not -path "./__pycache__/*" -exec python -m py_compile {} \;

# Lint
ruff check .
ruff check --fix .

# Type check
mypy cm_cli/ comfy_cli/

Adding New Endpoints

1. Add handler method in appropriate api/handlers/*.py file
2. Register route in api/routes.py (cm-cli) or comfy_cli_routes.py (comfy-cli)
3. Update this README or COMFY_CLI_API.md

Troubleshooting

cm-cli Not Found

Error: CM_CLI_NOT_FOUND

Solution: Ensure ComfyUI-Manager is installed in custom_nodes/ComfyUI-Manager/

comfy-cli Not Found

Error: COMFY_CLI_ERROR: comfy-cli not found

Solution:

pip install comfy-cli
comfy --version  # Verify installation

Port Conflicts

This extension uses ComfyUI's built-in server (default: 8188). No separate port needed.

Timeout Errors

Increase timeout in config/config.json for slow operations.

Security Considerations

• API Key: Set api_key in config if exposing externally
• Input Sanitization: All inputs validated before subprocess execution
• Path Traversal: Working directory locked to ComfyUI root

Documentation

• README.md - This file (main documentation)
• COMFY_CLI_API.md - Complete comfy-cli API reference
• COMFY_CLI_QUICKSTART.md - comfy-cli quick start guide
• AGENTS.md - Development guide for agentic coding

License

MIT License - See LICENSE file for details.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

References

• ComfyUI Documentation
• ComfyUI-Manager
• cm-cli Documentation
• comfy-cli