comfyui-skill-cli 0.1.0__py3-none-any.whl

comfyui_skill_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: comfyui-skill-cli
+Version: 0.1.0
+Summary: ComfyUI Skill CLI — Agent-friendly workflow management
+Author: HuangYuChuh
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/HuangYuChuh/ComfyUI_Skill_CLI
+Project-URL: Repository, https://github.com/HuangYuChuh/ComfyUI_Skill_CLI
+Project-URL: Issues, https://github.com/HuangYuChuh/ComfyUI_Skill_CLI/issues
+Keywords: comfyui,cli,agent,skill,workflow,ai,image-generation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9
+Requires-Dist: rich>=13.0
+Requires-Dist: requests>=2.28
+Dynamic: license-file
+
+# ComfyUI Skill CLI
+
+Agent-friendly command-line tool for managing and executing [ComfyUI](https://github.com/comfyanonymous/ComfyUI) workflow skills.
+
+## What is this?
+
+ComfyUI Skill CLI turns ComfyUI workflows into callable commands. Any AI agent that can run shell commands (Claude, Codex, OpenClaw, etc.) can use ComfyUI through this CLI.
+
+```bash
+# List available skills
+comfyui-skill list --json
+
+# Execute a workflow
+comfyui-skill run local/txt2img --args '{"prompt": "a white cat", "seed": 42}' --json
+
+# Check server health
+comfyui-skill server status --json
+```
+
+Every command supports `--json` for structured output. Pipe-friendly by default.
+
+## Install
+
+```bash
+pipx install comfyui-skill-cli
+```
+
+## Usage
+
+Run commands from within a [ComfyUI Skills](https://github.com/HuangYuChuh/ComfyUI_Skills_OpenClaw) project directory:
+
+```bash
+cd /path/to/your-skills-project
+comfyui-skill list
+```
+
+The CLI reads `config.json` and `data/` from the current working directory.
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `comfyui-skill list` | List all available skills with parameters |
+| `comfyui-skill info <id>` | Show skill details and parameter schema |
+| `comfyui-skill run <id> --args '{...}'` | Execute a skill (blocking) |
+| `comfyui-skill submit <id> --args '{...}'` | Submit a skill (non-blocking) |
+| `comfyui-skill status <prompt-id>` | Check execution status |
+| `comfyui-skill server list` | List configured servers |
+| `comfyui-skill server status` | Check if ComfyUI server is online |
+| `comfyui-skill deps check <id>` | Check missing dependencies |
+| `comfyui-skill deps install <id>` | Install missing dependencies |
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--json, -j` | Force JSON output |
+| `--server, -s` | Specify server ID |
+| `--dir, -d` | Specify data directory (default: current directory) |
+| `--verbose, -v` | Verbose output |
+
+### Output Modes
+
+- **TTY** → Rich tables and progress bars (human-friendly)
+- **Pipe / `--json`** → Structured JSON (agent-friendly)
+- **Errors** → Always stderr
+
+### Skill ID Format
+
+```bash
+comfyui-skill run local/txt2img          # server_id/workflow_id
+comfyui-skill run txt2img                # uses default server
+comfyui-skill run txt2img -s my_server   # explicit server
+```
+
+## For AI Agents
+
+This CLI is designed to be called from `SKILL.md` definitions:
+
+```markdown
+## Available Commands
+comfyui-skill list --json
+comfyui-skill info <server_id>/<workflow_id> --json
+comfyui-skill run <server_id>/<workflow_id> --args '{"prompt":"..."}' --json
+
+## Typical Flow
+1. `comfyui-skill server status --json` — verify server is online
+2. `comfyui-skill list --json` — discover available skills
+3. `comfyui-skill info <id> --json` — check required parameters
+4. `comfyui-skill run <id> --args '{...}' --json` — execute
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Invalid arguments |
+| 3 | Server connection failed |
+| 4 | Resource not found |
+| 5 | Execution failed |
+| 6 | Timeout |
+
+## Compatibility
+
+Built with [Typer](https://typer.tiangolo.com/), the same framework as [comfy-cli](https://github.com/Comfy-Org/comfy-cli). Designed to be integrated as a `comfy skills` subcommand in the future.
+
+## License
+
+MIT

comfyui_skill_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+comfyui_skill_cli-0.1.0.dist-info/licenses/LICENSE,sha256=fbdPU9jhPg5qMfAZ-JBFwSeaDYvfOU_0Jev9maM8ZAo,1068
+comfyui_skills_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+comfyui_skills_cli/__main__.py,sha256=5z9TeduMvrj9nhMuDlCRb5qkmvuCdfD6JQIvFZ_tXKM,86
+comfyui_skills_cli/client.py,sha256=kaZOYgDIL5jlLqIsUVxQrSz4dRhup6x6spF8p98KwO8,4584
+comfyui_skills_cli/config.py,sha256=uTzF4eL_fty3DDdIMZh6A6t2FKSOesCG0bwvpUtP2BY,987
+comfyui_skills_cli/main.py,sha256=N6OdYHmVYUMqqoA1gidQUcULRmXqbYvo26UKPkTnuQ8,1747
+comfyui_skills_cli/output.py,sha256=bPbmX2mWVuP77P9qJBdttunFpTSzPfW58zXpn9D0Z10,2834
+comfyui_skills_cli/storage.py,sha256=vk6i7Ynu6uszhs6V_3dtqt4nWW8EWgczlCsHTA9UVg0,3465
+comfyui_skills_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+comfyui_skills_cli/commands/deps.py,sha256=QoEm29y27Okw-4dhS4fs3yH0B7qadjBrUQfatzWzKWU,8292
+comfyui_skills_cli/commands/run.py,sha256=MDmbJMOb9tPaZKFebZQiMP77f8fygmAAmWixaMmh0jg,9856
+comfyui_skills_cli/commands/server.py,sha256=-6keAY64_N-XU7h_EV3uHx6DvTjkUGGsdkr-nlXTmYQ,1698
+comfyui_skills_cli/commands/skill.py,sha256=ColrJJ8tzeS7konXjm5INSqIXIcY8a-OcnbDTJo-rQM,1711
+comfyui_skill_cli-0.1.0.dist-info/METADATA,sha256=WRdvvn7JMHRC_GKSgUezWHZhc8AMS0_Pzy2xZn-ayPs,4435
+comfyui_skill_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+comfyui_skill_cli-0.1.0.dist-info/entry_points.txt,sha256=ny_jXyKiqTimpFwsxg-MaTt--7RhlhomfuHKPFfISVI,67
+comfyui_skill_cli-0.1.0.dist-info/top_level.txt,sha256=FOjZBQVWY4nOpBMsnQUW4kA8kpfAjLvMBUcRluK5220,19
+comfyui_skill_cli-0.1.0.dist-info/RECORD,,

comfyui_skill_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

comfyui_skill_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+comfyui-skill = comfyui_skills_cli.__main__:main

comfyui_skill_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HuangYuChuh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

comfyui_skill_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+comfyui_skills_cli

comfyui_skills_cli/__main__.py

@@ -0,0 +1,9 @@
+from .main import app
+
+
+def main():
+    app()
+
+
+if __name__ == "__main__":
+    main()

comfyui_skills_cli/client.py

@@ -0,0 +1,139 @@
+"""ComfyUI HTTP client — all server communication goes through here."""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from typing import Any
+
+import requests
+
+
+class ComfyUIClient:
+    def __init__(self, server_url: str, auth: str = "", comfy_api_key: str = "", timeout: float = 30.0):
+        self.server_url = server_url.rstrip("/")
+        self.auth = auth
+        self.comfy_api_key = comfy_api_key
+        self.timeout = timeout
+
+    def _headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        if self.auth:
+            headers["Authorization"] = f"Bearer {self.auth}"
+        return headers
+
+    def _get(self, path: str, **kwargs: Any) -> requests.Response:
+        return requests.get(
+            f"{self.server_url}{path}",
+            headers=self._headers(),
+            timeout=self.timeout,
+            **kwargs,
+        )
+
+    def _post(self, path: str, json_data: Any = None, **kwargs: Any) -> requests.Response:
+        return requests.post(
+            f"{self.server_url}{path}",
+            headers=self._headers(),
+            json=json_data,
+            timeout=self.timeout,
+            **kwargs,
+        )
+
+    # -- Health --
+
+    def check_health(self) -> dict[str, Any]:
+        try:
+            resp = self._get("/system_stats")
+            resp.raise_for_status()
+            return {"status": "online", "data": resp.json()}
+        except (requests.RequestException, ValueError) as exc:
+            return {"status": "offline", "error": str(exc)}
+
+    # -- Prompt execution --
+
+    def queue_prompt(self, workflow: dict[str, Any]) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "prompt": workflow,
+            "client_id": str(uuid.uuid4()),
+        }
+        if self.comfy_api_key:
+            payload["extra_data"] = {"api_key_comfy_org": self.comfy_api_key}
+        resp = self._post("/prompt", json_data=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_history(self, prompt_id: str) -> dict[str, Any] | None:
+        resp = self._get(f"/history/{prompt_id}")
+        if resp.status_code != 200:
+            return None
+        data = resp.json()
+        return data.get(prompt_id)
+
+    def get_queue(self) -> dict[str, Any]:
+        resp = self._get("/queue")
+        resp.raise_for_status()
+        return resp.json()
+
+    def download_output(self, filename: str, subfolder: str = "", output_type: str = "output") -> bytes:
+        resp = self._get("/view", params={
+            "filename": filename,
+            "subfolder": subfolder,
+            "type": output_type,
+        })
+        resp.raise_for_status()
+        return resp.content
+
+    # -- Node info --
+
+    def get_object_info(self) -> dict[str, Any]:
+        resp = self._get("/object_info")
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_models(self, folder: str) -> list[str]:
+        resp = self._get(f"/models/{folder}")
+        resp.raise_for_status()
+        return resp.json()
+
+    # -- Manager API (ComfyUI-Manager plugin) --
+
+    def manager_start_queue(self) -> bool:
+        try:
+            resp = self._get("/manager/queue/start", timeout=10)
+            return resp.status_code < 500
+        except requests.RequestException:
+            return False
+
+    def manager_install_node(self, repo_url: str, pkg_name: str) -> dict[str, Any]:
+        resp = self._post("/manager/queue/install", json_data={
+            "id": pkg_name,
+            "url": repo_url,
+            "install_type": "git-clone",
+        })
+        if resp.status_code == 404:
+            return {"success": False, "error": "ComfyUI Manager not installed"}
+        if resp.status_code >= 400:
+            return {"success": False, "error": f"Manager API error: {resp.status_code}"}
+        return {"success": True}
+
+    def manager_queue_status(self) -> dict[str, Any] | None:
+        try:
+            resp = self._get("/manager/queue/status", timeout=10)
+            if resp.status_code != 200:
+                return None
+            return resp.json()
+        except (requests.RequestException, ValueError):
+            return None
+
+    def manager_wait_for_queue(self, max_polls: int = 60, interval: float = 3.0) -> bool:
+        for _ in range(max_polls):
+            time.sleep(interval)
+            status = self.manager_queue_status()
+            if status is None:
+                continue
+            total = status.get("total", 0)
+            done = status.get("done", 0)
+            if total > 0 and done >= total:
+                return True
+        return False

comfyui_skills_cli/commands/deps.py

@@ -0,0 +1,232 @@
+"""comfyui-skill deps check / install"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import typer
+
+from ..client import ComfyUIClient
+from ..config import get_base_dir, get_default_server_id, get_server, load_config
+from ..output import output_error, output_event, output_result
+from ..storage import get_workflow_data
+
+app = typer.Typer()
+
+# Known model loader node types and the input field that references a model file
+MODEL_LOADER_MAP: dict[str, tuple[str, str]] = {
+    "CheckpointLoaderSimple": ("ckpt_name", "checkpoints"),
+    "CheckpointLoader": ("ckpt_name", "checkpoints"),
+    "LoraLoader": ("lora_name", "loras"),
+    "LoraLoaderModelOnly": ("lora_name", "loras"),
+    "VAELoader": ("vae_name", "vae"),
+    "ControlNetLoader": ("control_net_name", "controlnet"),
+    "CLIPLoader": ("clip_name", "text_encoders"),
+    "UNETLoader": ("unet_name", "diffusion_models"),
+    "unCLIPCheckpointLoader": ("ckpt_name", "checkpoints"),
+    "StyleModelLoader": ("style_model_name", "style_models"),
+    "CLIPVisionLoader": ("clip_name", "clip_vision"),
+    "UpscaleModelLoader": ("model_name", "upscale_models"),
+    "PhotoMakerLoader": ("photomaker_model_name", "photomaker"),
+}
+
+
+@app.command("check")
+def deps_check(
+    ctx: typer.Context,
+    skill_id: str = typer.Argument(help="Skill ID: server_id/workflow_id"),
+):
+    """Check if a skill's dependencies (custom nodes and models) are installed."""
+    base_dir = get_base_dir(ctx.obj.get("base_dir", ""))
+    config = load_config(base_dir)
+
+    if "/" in skill_id:
+        server_id, workflow_id = skill_id.split("/", 1)
+    else:
+        server_id = ctx.obj.get("server") or get_default_server_id(config)
+        workflow_id = skill_id
+
+    server_config = get_server(config, server_id)
+    if not server_config:
+        output_error(ctx, "SERVER_NOT_FOUND", f'Server "{server_id}" not found.')
+        return
+
+    workflow_data = get_workflow_data(base_dir, server_id, workflow_id)
+    if not workflow_data:
+        output_error(ctx, "SKILL_NOT_FOUND", f'Skill "{skill_id}" not found.')
+        return
+
+    client = ComfyUIClient(
+        server_url=server_config.get("url", "http://127.0.0.1:8188"),
+        auth=server_config.get("auth", ""),
+    )
+
+    # Check server is reachable
+    health = client.check_health()
+    if health.get("status") != "online":
+        output_error(ctx, "SERVER_OFFLINE", f'Server "{server_id}" is offline.',
+                     hint="Start ComfyUI first, then retry.")
+        return
+
+    # Get installed nodes
+    try:
+        object_info = client.get_object_info()
+    except Exception as exc:
+        output_error(ctx, "OBJECT_INFO_FAILED", f"Failed to query /object_info: {exc}")
+        return
+    installed_nodes = set(object_info.keys())
+
+    # Extract required nodes from workflow
+    required_nodes = set()
+    for node in workflow_data.values():
+        if isinstance(node, dict) and "class_type" in node:
+            required_nodes.add(node["class_type"])
+
+    # Find missing nodes
+    missing_nodes = []
+    for class_type in sorted(required_nodes - installed_nodes):
+        missing_nodes.append({
+            "class_type": class_type,
+            "can_auto_install": False,
+        })
+
+    # Check models
+    missing_models = _check_missing_models(client, workflow_data)
+
+    is_ready = len(missing_nodes) == 0 and len(missing_models) == 0
+
+    output_result(ctx, {
+        "is_ready": is_ready,
+        "missing_nodes": missing_nodes,
+        "missing_models": missing_models,
+        "total_nodes_required": len(required_nodes),
+        "total_nodes_installed": len(required_nodes) - len(missing_nodes),
+    })
+
+
+@app.command("install")
+def deps_install(
+    ctx: typer.Context,
+    skill_id: str = typer.Argument(help="Skill ID: server_id/workflow_id"),
+    repos: str = typer.Option("[]", "--repos", "-r", help="JSON array of git repo URLs to install"),
+):
+    """Install missing custom node packages via ComfyUI Manager."""
+    base_dir = get_base_dir(ctx.obj.get("base_dir", ""))
+    config = load_config(base_dir)
+
+    if "/" in skill_id:
+        server_id, workflow_id = skill_id.split("/", 1)
+    else:
+        server_id = ctx.obj.get("server") or get_default_server_id(config)
+        workflow_id = skill_id
+
+    server_config = get_server(config, server_id)
+    if not server_config:
+        output_error(ctx, "SERVER_NOT_FOUND", f'Server "{server_id}" not found.')
+        return
+
+    # Parse repos
+    try:
+        repo_urls = json.loads(repos)
+        if not isinstance(repo_urls, list):
+            output_error(ctx, "INVALID_ARGS", "--repos must be a JSON array of URLs")
+            return
+    except json.JSONDecodeError:
+        output_error(ctx, "INVALID_ARGS", "Invalid JSON for --repos")
+        return
+
+    if not repo_urls:
+        output_error(ctx, "INVALID_ARGS", "No repo URLs provided. Use --repos '[\"https://github.com/...\"]'")
+        return
+
+    client = ComfyUIClient(
+        server_url=server_config.get("url", "http://127.0.0.1:8188"),
+        auth=server_config.get("auth", ""),
+    )
+
+    # Start manager queue
+    if not client.manager_start_queue():
+        output_error(ctx, "MANAGER_UNAVAILABLE",
+                     "ComfyUI Manager is not available on this server.",
+                     hint="Install ComfyUI-Manager first: https://github.com/ltdrdata/ComfyUI-Manager")
+        return
+
+    results = []
+    needs_restart = False
+
+    for repo_url in repo_urls:
+        pkg_name = repo_url.rstrip("/").split("/")[-1].replace(".git", "")
+        output_event(ctx, "installing", package=pkg_name, source=repo_url)
+
+        install_result = client.manager_install_node(repo_url, pkg_name)
+
+        if install_result.get("success"):
+            # Wait for queue to finish
+            success = client.manager_wait_for_queue(max_polls=60, interval=3.0)
+            results.append({
+                "package": pkg_name,
+                "source": repo_url,
+                "success": success,
+                "method": "manager_queue",
+                "message": "installed via Manager" if success else "Manager queue timed out",
+            })
+            if success:
+                needs_restart = True
+                output_event(ctx, "installed", package=pkg_name, success=True)
+            else:
+                output_event(ctx, "installed", package=pkg_name, success=False, message="queue timed out")
+        else:
+            error_msg = install_result.get("error", "unknown error")
+            results.append({
+                "package": pkg_name,
+                "source": repo_url,
+                "success": False,
+                "message": error_msg,
+            })
+            output_event(ctx, "installed", package=pkg_name, success=False, message=error_msg)
+
+    output_result(ctx, {
+        "results": results,
+        "needs_restart": needs_restart,
+        "installed": sum(1 for r in results if r["success"]),
+        "failed": sum(1 for r in results if not r["success"]),
+    })
+
+
+def _check_missing_models(client: ComfyUIClient, workflow_data: dict[str, Any]) -> list[dict[str, str]]:
+    """Check for missing model files referenced in the workflow."""
+    missing = []
+    checked_folders: dict[str, set[str]] = {}
+
+    for node_id, node in workflow_data.items():
+        if not isinstance(node, dict):
+            continue
+        class_type = node.get("class_type", "")
+        if class_type not in MODEL_LOADER_MAP:
+            continue
+
+        field_name, folder = MODEL_LOADER_MAP[class_type]
+        inputs = node.get("inputs", {})
+        model_filename = inputs.get(field_name)
+
+        if not model_filename or not isinstance(model_filename, str):
+            continue
+
+        # Cache the model list per folder
+        if folder not in checked_folders:
+            try:
+                models = client.get_models(folder)
+                checked_folders[folder] = set(models) if isinstance(models, list) else set()
+            except Exception:
+                checked_folders[folder] = set()
+
+        if model_filename not in checked_folders[folder]:
+            missing.append({
+                "filename": model_filename,
+                "folder": folder,
+                "loader_node": class_type,
+                "node_id": str(node_id),
+            })
+
+    return missing

comfyui_skills_cli/commands/run.py

@@ -0,0 +1,273 @@
+"""comfy-skills run / submit / status"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import time
+import uuid
+from typing import Any
+
+import typer
+
+from ..client import ComfyUIClient
+from ..config import get_base_dir, get_default_server_id, get_server, load_config
+from ..output import OutputFormat, get_output_format, is_machine_mode, output_error, output_event, output_result
+from ..storage import get_schema, get_workflow_data
+
+_POLL_INITIAL = 1.0
+_POLL_MAX = 10.0
+_POLL_FACTOR = 1.5
+
+
+def run_cmd(
+    ctx: typer.Context,
+    skill_id: str = typer.Argument(help="Skill ID: server_id/workflow_id or workflow_id"),
+    args: str = typer.Option("{}", "--args", "-a", help="JSON parameters"),
+):
+    """Execute a skill (blocking — waits for completion)."""
+    base_dir, server_id, workflow_id = _resolve_skill(ctx, skill_id)
+    client, schema_data, workflow_data = _prepare(ctx, base_dir, server_id, workflow_id)
+
+    input_args = _parse_args(ctx, args)
+    parameters = _get_parameters(schema_data)
+
+    # Inject parameters into workflow
+    workflow = _inject_params(workflow_data, parameters, input_args)
+
+    # Submit
+    try:
+        result = client.queue_prompt(workflow)
+    except Exception as exc:
+        output_error(ctx, "SUBMIT_FAILED", f"Failed to submit workflow: {exc}")
+        return
+
+    prompt_id = result.get("prompt_id", "")
+    fmt = get_output_format(ctx)
+
+    # stream-json: emit events as they happen
+    output_event(ctx, "queued", prompt_id=prompt_id)
+
+    # Rich progress for text mode
+    if fmt == OutputFormat.TEXT:
+        from rich.console import Console
+        console = Console(stderr=True)
+        console.print(f"[dim]Queued: {prompt_id}[/dim]")
+
+    # Poll until complete
+    poll_interval = _POLL_INITIAL
+    prev_status = ""
+    while True:
+        history = client.get_history(prompt_id)
+        if history:
+            outputs = history.get("outputs", {})
+            status_info = history.get("status", {})
+
+            if status_info.get("completed", False) or outputs:
+                images = _collect_outputs(outputs)
+                output_event(ctx, "completed", prompt_id=prompt_id, outputs=images)
+
+                # Final result — json and stream-json both get this
+                if fmt == OutputFormat.STREAM_JSON:
+                    return
+                output_result(ctx, {
+                    "status": "success",
+                    "prompt_id": prompt_id,
+                    "outputs": images,
+                })
+                return
+
+            if status_info.get("status_str") == "error":
+                error_msg = _format_errors(history)
+                output_event(ctx, "error", prompt_id=prompt_id, message=error_msg)
+                output_error(ctx, "EXECUTION_FAILED", error_msg)
+                return
+
+        # Check queue position
+        queue = client.get_queue()
+        current_status = ""
+        for item in queue.get("queue_running", []):
+            if len(item) > 1 and item[1] == prompt_id:
+                current_status = "running"
+                break
+        if not current_status:
+            for i, item in enumerate(queue.get("queue_pending", [])):
+                if len(item) > 1 and item[1] == prompt_id:
+                    current_status = f"queued:{i}"
+                    break
+
+        if current_status and current_status != prev_status:
+            if current_status == "running":
+                output_event(ctx, "running", prompt_id=prompt_id)
+                if fmt == OutputFormat.TEXT:
+                    console.print("[yellow]Running...[/yellow]")
+            elif current_status.startswith("queued:"):
+                pos = current_status.split(":")[1]
+                output_event(ctx, "queued", prompt_id=prompt_id, position=int(pos))
+            prev_status = current_status
+
+        time.sleep(poll_interval)
+        poll_interval = min(poll_interval * _POLL_FACTOR, _POLL_MAX)
+
+
+def submit_cmd(
+    ctx: typer.Context,
+    skill_id: str = typer.Argument(help="Skill ID: server_id/workflow_id or workflow_id"),
+    args: str = typer.Option("{}", "--args", "-a", help="JSON parameters"),
+):
+    """Submit a skill for execution (non-blocking — returns immediately)."""
+    base_dir, server_id, workflow_id = _resolve_skill(ctx, skill_id)
+    client, schema_data, workflow_data = _prepare(ctx, base_dir, server_id, workflow_id)
+
+    input_args = _parse_args(ctx, args)
+    parameters = _get_parameters(schema_data)
+    workflow = _inject_params(workflow_data, parameters, input_args)
+
+    try:
+        result = client.queue_prompt(workflow)
+    except Exception as exc:
+        output_error(ctx, "SUBMIT_FAILED", f"Failed to submit workflow: {exc}")
+        return
+
+    output_result(ctx, {
+        "status": "submitted",
+        "prompt_id": result.get("prompt_id", ""),
+    })
+
+
+def status_cmd(
+    ctx: typer.Context,
+    prompt_id: str = typer.Argument(help="Prompt ID from submit"),
+):
+    """Check execution status of a submitted workflow."""
+    base_dir = get_base_dir(ctx.obj.get("base_dir", ""))
+    config = load_config(base_dir)
+    server_id = ctx.obj.get("server") or get_default_server_id(config)
+    server_config = get_server(config, server_id)
+
+    if not server_config:
+        output_error(ctx, "SERVER_NOT_FOUND", f'Server "{server_id}" not found.')
+        return
+
+    client = _build_client(server_config)
+    history = client.get_history(prompt_id)
+
+    if history:
+        status_info = history.get("status", {})
+        outputs = history.get("outputs", {})
+        if status_info.get("completed", False) or outputs:
+            images = _collect_outputs(outputs)
+            output_result(ctx, {"status": "success", "prompt_id": prompt_id, "outputs": images})
+            return
+        if status_info.get("status_str") == "error":
+            output_result(ctx, {"status": "error", "prompt_id": prompt_id, "error": _format_errors(history)})
+            return
+
+    # Check queue
+    queue = client.get_queue()
+    for item in queue.get("queue_running", []):
+        if item[1] == prompt_id:
+            output_result(ctx, {"status": "running", "prompt_id": prompt_id})
+            return
+    for i, item in enumerate(queue.get("queue_pending", [])):
+        if item[1] == prompt_id:
+            output_result(ctx, {"status": "queued", "prompt_id": prompt_id, "position": i})
+            return
+
+    output_result(ctx, {"status": "not_found", "prompt_id": prompt_id})
+
+
+# -- Helpers --
+
+def _resolve_skill(ctx: typer.Context, skill_id: str) -> tuple[Any, str, str]:
+    base_dir = get_base_dir(ctx.obj.get("base_dir", ""))
+    if "/" in skill_id:
+        server_id, workflow_id = skill_id.split("/", 1)
+    else:
+        config = load_config(base_dir)
+        server_id = ctx.obj.get("server") or get_default_server_id(config)
+        workflow_id = skill_id
+    return base_dir, server_id, workflow_id
+
+
+def _prepare(ctx: typer.Context, base_dir: Any, server_id: str, workflow_id: str):
+    config = load_config(base_dir)
+    server_config = get_server(config, server_id)
+    if not server_config:
+        output_error(ctx, "SERVER_NOT_FOUND", f'Server "{server_id}" not found.')
+
+    schema_data = get_schema(base_dir, server_id, workflow_id)
+    workflow_data = get_workflow_data(base_dir, server_id, workflow_id)
+    if not workflow_data:
+        output_error(ctx, "SKILL_NOT_FOUND", f'Skill "{server_id}/{workflow_id}" not found.')
+
+    client = _build_client(server_config)
+    return client, schema_data or {}, workflow_data
+
+
+def _build_client(server_config: dict[str, Any]) -> ComfyUIClient:
+    return ComfyUIClient(
+        server_url=server_config.get("url", "http://127.0.0.1:8188"),
+        auth=server_config.get("auth", ""),
+        comfy_api_key=server_config.get("comfy_api_key", ""),
+    )
+
+
+def _parse_args(ctx: typer.Context, args_str: str) -> dict[str, Any]:
+    try:
+        return json.loads(args_str)
+    except json.JSONDecodeError as exc:
+        output_error(ctx, "INVALID_ARGS", f"Invalid JSON in --args: {exc}")
+        return {}
+
+
+def _get_parameters(schema_data: dict[str, Any]) -> dict[str, Any]:
+    parameters = dict(schema_data.get("parameters", {}))
+    ui_parameters = schema_data.get("ui_parameters", {})
+    if ui_parameters:
+        for key, ui_param in ui_parameters.items():
+            name = ui_param.get("name", key)
+            if name not in parameters and ui_param.get("exposed", False):
+                parameters[name] = ui_param
+    return parameters
+
+
+def _inject_params(
+    workflow_data: dict[str, Any],
+    parameters: dict[str, Any],
+    args: dict[str, Any],
+) -> dict[str, Any]:
+    workflow = copy.deepcopy(workflow_data)
+    for key, value in args.items():
+        if key not in parameters:
+            continue
+        node_id = str(parameters[key].get("node_id", ""))
+        field = parameters[key].get("field", "")
+        if node_id in workflow and isinstance(workflow[node_id], dict) and "inputs" in workflow[node_id]:
+            workflow[node_id]["inputs"][field] = value
+    return workflow
+
+
+def _collect_outputs(outputs: dict[str, Any]) -> list[dict[str, str]]:
+    images = []
+    for node_output in outputs.values():
+        if not isinstance(node_output, dict):
+            continue
+        for img in node_output.get("images", []):
+            images.append({
+                "filename": img.get("filename", ""),
+                "subfolder": img.get("subfolder", ""),
+                "type": img.get("type", "output"),
+            })
+    return images
+
+
+def _format_errors(history: dict[str, Any]) -> str:
+    status_info = history.get("status", {})
+    messages = status_info.get("messages", [])
+    parts = []
+    for msg in messages:
+        if isinstance(msg, list) and len(msg) >= 2:
+            parts.append(str(msg[1]))
+    return "; ".join(parts) if parts else "Workflow execution failed"

comfyui_skills_cli/commands/server.py

@@ -0,0 +1,57 @@
+"""comfy-skills server list / status"""
+
+from __future__ import annotations
+
+import typer
+
+from ..client import ComfyUIClient
+from ..config import get_base_dir, get_default_server_id, get_server, get_servers, load_config
+from ..output import output_error, output_result
+
+app = typer.Typer()
+
+
+@app.command("list")
+def server_list(ctx: typer.Context):
+    """List all configured servers."""
+    base_dir = get_base_dir(ctx.obj.get("base_dir", ""))
+    config = load_config(base_dir)
+    servers = get_servers(config)
+    result = [
+        {
+            "id": s.get("id", ""),
+            "name": s.get("name", ""),
+            "url": s.get("url", ""),
+            "enabled": s.get("enabled", True),
+        }
+        for s in servers
+    ]
+    output_result(ctx, result)
+
+
+@app.command("status")
+def server_status(
+    ctx: typer.Context,
+    server_id: str = typer.Argument("", help="Server ID (default: default server)"),
+):
+    """Check if a ComfyUI server is online."""
+    base_dir = get_base_dir(ctx.obj.get("base_dir", ""))
+    config = load_config(base_dir)
+    sid = server_id or ctx.obj.get("server") or get_default_server_id(config)
+    server_config = get_server(config, sid)
+
+    if not server_config:
+        output_error(ctx, "SERVER_NOT_FOUND", f'Server "{sid}" not found.',
+                     hint="Run `comfy-skills server list` to see configured servers.")
+        return
+
+    client = ComfyUIClient(
+        server_url=server_config.get("url", "http://127.0.0.1:8188"),
+        auth=server_config.get("auth", ""),
+    )
+    health = client.check_health()
+    output_result(ctx, {
+        "server_id": sid,
+        "url": server_config.get("url", ""),
+        **health,
+    })

comfyui_skills_cli/commands/skill.py

@@ -0,0 +1,54 @@
+"""comfy-skills skill list / info"""
+
+from __future__ import annotations
+
+import typer
+
+from ..config import get_base_dir, get_default_server_id, get_servers, load_config
+from ..output import output_error, output_result
+from ..storage import get_workflow_detail, list_workflows
+
+app = typer.Typer()
+
+
+@app.command("list")
+def skill_list(ctx: typer.Context):
+    """List all available skills."""
+    base_dir = get_base_dir(ctx.obj.get("base_dir", ""))
+    config = load_config(base_dir)
+    server_id = ctx.obj.get("server") or ""
+
+    all_skills = []
+    if server_id:
+        all_skills = list_workflows(base_dir, server_id)
+    else:
+        for s in get_servers(config):
+            if s.get("enabled", True):
+                all_skills.extend(list_workflows(base_dir, s["id"]))
+
+    output_result(ctx, all_skills)
+
+
+@app.command("info")
+def skill_info(
+    ctx: typer.Context,
+    skill_id: str = typer.Argument(help="Skill ID in format: server_id/workflow_id"),
+):
+    """Show skill details including parameter schema."""
+    base_dir = get_base_dir(ctx.obj.get("base_dir", ""))
+
+    if "/" in skill_id:
+        server_id, workflow_id = skill_id.split("/", 1)
+    else:
+        config = load_config(base_dir)
+        server_id = ctx.obj.get("server") or get_default_server_id(config)
+        workflow_id = skill_id
+
+    detail = get_workflow_detail(base_dir, server_id, workflow_id)
+    if detail is None:
+        output_error(ctx, "SKILL_NOT_FOUND", f'Skill "{skill_id}" not found.',
+                     hint="Run `comfy-skills skill list` to see available skills.")
+
+    # Don't include full workflow_data in info output (too large)
+    detail.pop("workflow_data", None)
+    output_result(ctx, detail)

comfyui_skills_cli/config.py

@@ -0,0 +1,36 @@
+"""Read config.json and data/ from the current working directory."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def get_base_dir(override: str = "") -> Path:
+    if override:
+        return Path(override).resolve()
+    return Path.cwd()
+
+
+def load_config(base_dir: Path) -> dict[str, Any]:
+    config_path = base_dir / "config.json"
+    if not config_path.exists():
+        return {"servers": []}
+    with open(config_path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def get_servers(config: dict[str, Any]) -> list[dict[str, Any]]:
+    return [s for s in config.get("servers", []) if isinstance(s, dict)]
+
+
+def get_server(config: dict[str, Any], server_id: str) -> dict[str, Any] | None:
+    for server in get_servers(config):
+        if server.get("id") == server_id:
+            return server
+    return None
+
+
+def get_default_server_id(config: dict[str, Any]) -> str:
+    return config.get("default_server", "local")

comfyui_skills_cli/main.py

@@ -0,0 +1,50 @@
+"""ComfyUI Skill CLI — Typer app with global options and subcommand registration."""
+
+from __future__ import annotations
+
+import typer
+
+from .commands import deps, run, server, skill
+
+app = typer.Typer(
+    name="comfyui-skill",
+    help="ComfyUI Skill CLI — Agent-friendly workflow management",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(False, "--json", "-j", help="JSON output (shortcut for --output-format json)"),
+    output_format: str = typer.Option("", "--output-format", help="Output format: text, json, stream-json"),
+    server_id: str = typer.Option("", "--server", "-s", help="Server ID"),
+    base_dir: str = typer.Option("", "--dir", "-d", help="Data directory (default: current directory)"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Verbose output"),
+):
+    ctx.ensure_object(dict)
+    ctx.obj["json"] = json_output
+    ctx.obj["output_format"] = output_format
+    ctx.obj["server"] = server_id
+    ctx.obj["base_dir"] = base_dir
+    ctx.obj["verbose"] = verbose
+
+
+# Subcommand groups — each needs a callback to inherit parent context
+for sub_app in [deps.app, server.app]:
+    @sub_app.callback()
+    def _pass_context(ctx: typer.Context):
+        if ctx.parent and ctx.parent.obj:
+            ctx.ensure_object(dict)
+            ctx.obj.update(ctx.parent.obj)
+
+app.add_typer(deps.app, name="deps", help="Manage dependencies")
+app.add_typer(server.app, name="server", help="Manage servers")
+
+# Top-level commands
+app.command("list")(skill.skill_list)
+app.command("info")(skill.skill_info)
+app.command("run")(run.run_cmd)
+app.command("submit")(run.submit_cmd)
+app.command("status")(run.status_cmd)

comfyui_skills_cli/output.py

@@ -0,0 +1,85 @@
+"""Unified output formatting — the only place that handles text / JSON / stream-JSON."""
+
+from __future__ import annotations
+
+import json
+import sys
+from enum import Enum
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+
+class OutputFormat(str, Enum):
+    TEXT = "text"                # Rich tables, progress bars (human)
+    JSON = "json"               # Single JSON result at end (agent, one-shot)
+    STREAM_JSON = "stream-json" # NDJSON events in real time (agent, streaming)
+
+
+def get_output_format(ctx: typer.Context) -> OutputFormat:
+    if ctx.obj:
+        fmt = ctx.obj.get("output_format", "")
+        if fmt:
+            return OutputFormat(fmt)
+        if ctx.obj.get("json"):
+            return OutputFormat.JSON
+    if not sys.stdout.isatty():
+        return OutputFormat.JSON
+    return OutputFormat.TEXT
+
+
+def is_machine_mode(ctx: typer.Context) -> bool:
+    return get_output_format(ctx) in (OutputFormat.JSON, OutputFormat.STREAM_JSON)
+
+
+def output_result(ctx: typer.Context, data: Any) -> None:
+    fmt = get_output_format(ctx)
+    if fmt in (OutputFormat.JSON, OutputFormat.STREAM_JSON):
+        indent = 2 if sys.stdout.isatty() else None
+        json.dump(data, sys.stdout, ensure_ascii=False, indent=indent, default=str)
+        sys.stdout.write("\n")
+    else:
+        _print_rich(data)
+
+
+def output_error(ctx: typer.Context, code: str, message: str, hint: str = "") -> None:
+    if is_machine_mode(ctx):
+        err: dict[str, Any] = {"error": {"code": code, "message": message}}
+        if hint:
+            err["error"]["hint"] = hint
+        json.dump(err, sys.stderr, ensure_ascii=False)
+        sys.stderr.write("\n")
+    else:
+        console = Console(stderr=True)
+        console.print(f"[red bold]Error:[/red bold] {message}")
+        if hint:
+            console.print(f"[dim]Hint: {hint}[/dim]")
+    raise typer.Exit(code=1)
+
+
+def output_event(ctx: typer.Context, event_type: str, **data: Any) -> None:
+    """Emit a single NDJSON event line. Only outputs in stream-json mode."""
+    fmt = get_output_format(ctx)
+    if fmt == OutputFormat.STREAM_JSON:
+        json.dump({"event": event_type, **data}, sys.stdout, ensure_ascii=False, default=str)
+        sys.stdout.write("\n")
+        sys.stdout.flush()
+
+
+def _print_rich(data: Any) -> None:
+    console = Console()
+    if isinstance(data, list) and data and isinstance(data[0], dict):
+        table = Table()
+        keys = list(data[0].keys())
+        for key in keys:
+            table.add_column(key)
+        for item in data:
+            table.add_row(*[str(item.get(k, "")) for k in keys])
+        console.print(table)
+    elif isinstance(data, dict):
+        for key, value in data.items():
+            console.print(f"[bold]{key}:[/bold] {value}")
+    else:
+        console.print(data)

comfyui_skills_cli/storage.py

@@ -0,0 +1,104 @@
+"""Read workflow and schema data from the data/ directory."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def list_workflows(base_dir: Path, server_id: str) -> list[dict[str, Any]]:
+    data_dir = base_dir / "data" / server_id
+    if not data_dir.exists():
+        return []
+
+    workflows = []
+    for workflow_dir in sorted(data_dir.iterdir()):
+        if not workflow_dir.is_dir():
+            continue
+        schema_path = workflow_dir / "schema.json"
+        if not schema_path.exists():
+            continue
+        schema = _load_json(schema_path)
+        workflows.append({
+            "workflow_id": workflow_dir.name,
+            "server_id": server_id,
+            "description": schema.get("description", ""),
+            "enabled": schema.get("enabled", True),
+            "parameters": _summarize_params(schema),
+        })
+    return workflows
+
+
+def get_workflow_detail(base_dir: Path, server_id: str, workflow_id: str) -> dict[str, Any] | None:
+    workflow_dir = base_dir / "data" / server_id / workflow_id
+    if not workflow_dir.is_dir():
+        return None
+
+    schema = _load_json(workflow_dir / "schema.json") if (workflow_dir / "schema.json").exists() else {}
+    workflow_data = _load_json(workflow_dir / "workflow.json") if (workflow_dir / "workflow.json").exists() else {}
+
+    parameters = schema.get("parameters", {})
+    ui_parameters = schema.get("ui_parameters", {})
+    merged = _merge_parameters(parameters, ui_parameters)
+
+    return {
+        "workflow_id": workflow_id,
+        "server_id": server_id,
+        "description": schema.get("description", ""),
+        "enabled": schema.get("enabled", True),
+        "parameters": merged,
+        "workflow_data": workflow_data,
+    }
+
+
+def get_workflow_data(base_dir: Path, server_id: str, workflow_id: str) -> dict[str, Any] | None:
+    path = base_dir / "data" / server_id / workflow_id / "workflow.json"
+    if not path.exists():
+        return None
+    return _load_json(path)
+
+
+def get_schema(base_dir: Path, server_id: str, workflow_id: str) -> dict[str, Any] | None:
+    path = base_dir / "data" / server_id / workflow_id / "schema.json"
+    if not path.exists():
+        return None
+    return _load_json(path)
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _summarize_params(schema: dict[str, Any]) -> dict[str, Any]:
+    parameters = schema.get("parameters", {})
+    ui_parameters = schema.get("ui_parameters", {})
+    merged = _merge_parameters(parameters, ui_parameters)
+    return {
+        name: {
+            "type": p.get("type", "string"),
+            "required": p.get("required", False),
+            "description": p.get("description", ""),
+        }
+        for name, p in merged.items()
+        if p.get("exposed", True)
+    }
+
+
+def _merge_parameters(
+    parameters: dict[str, Any],
+    ui_parameters: dict[str, Any],
+) -> dict[str, Any]:
+    if not ui_parameters:
+        return parameters
+    merged = dict(parameters)
+    for key, ui_param in ui_parameters.items():
+        name = ui_param.get("name", key)
+        if name in merged:
+            for field in ("type", "required", "description", "default"):
+                if field in ui_param and ui_param[field]:
+                    merged[name][field] = ui_param[field]
+        elif ui_param.get("exposed", False):
+            merged[name] = ui_param
+    return merged