run-comfy-workflow

name	run-comfy-workflow
description	Execute an existing VibeComfy/ComfyUI workflow, ready template, recipe, or scratchpad and collect outputs. Use when the user asks to run, queue, execute, generate, render, smoke test, use a local/remote ComfyUI runtime, or run on RunPod.

Run Comfy Workflow

Use this for execution. If the graph must change first, use edit-comfy-workflow. If ComfyUI or paths are not configured, use vibecomfy-setup. If a run fails, use debug-comfy-workflow.

Preflight

vibecomfy inspect <workflow>
vibecomfy validate <workflow>
vibecomfy doctor <workflow> --json

For raw JSON, treat the file as import evidence and convert the positional source before running:

vibecomfy port check <workflow.json> --json
vibecomfy nodes reconcile --workflow <workflow.json> --json
vibecomfy port convert <workflow.json> --out out/scratchpads/<name>.py --json

Embedded Runtime

Use embedded when local ComfyUI is discoverable in the active environment:

vibecomfy run <workflow.py> --runtime embedded
vibecomfy run image/z_image --ready --runtime embedded

Prompt/seed/steps CLI overrides only work when the workflow exposes matching public inputs:

vibecomfy run image/z_image --ready --runtime embedded --prompt "..." --seed 7 --steps 20

Use dependency helpers only when the user wants VibeComfy to prepare local runtime assets:

vibecomfy run <workflow.py> --runtime embedded --ensure-packs --ensure-models

--ensure-packs is embedded-only.

Existing ComfyUI Server

Use this when the user already has ComfyUI running locally or remotely:

vibecomfy run <workflow.py> --runtime server --server-url http://127.0.0.1:8188
vibecomfy run image/z_image --ready --runtime server --server-url http://127.0.0.1:8188

Python-format workflows work against an existing server. VibeComfy imports the workflow's build(), compiles the VibeWorkflow to API JSON, and queues that JSON to the server.

The external server must already have the required custom nodes and models unless the user separately stages them into that server's environment. Do not use --ensure-packs with server runtime. --ensure-models can only prepare the local/shared model path VibeComfy can see.

For a VibeComfy-managed local HTTP server, omit --server-url:

vibecomfy run <workflow.py> --runtime server

--runtime auto attaches to an active default session when one exists; otherwise it falls back to embedded execution.

RunPod

Use RunPod when requested or when local execution is unavailable and a GPU run is necessary. The acceptance script is a retired fail-closed placeholder; it exits before provisioning and cannot establish an end-to-end result. The validation and matrix commands are live remote operations:

python scripts/runpod_acceptance.py  # refusal only; no live acceptance
python scripts/runpod_validate.py   # one remote smoke
VIBECOMFY_MATRIX_SCOPE=<family> uv run python scripts/runpod_corpus_matrix.py  # remote matrix
pytest --runpod -m runpod tests/smoke/test_layer2_runpod_ops.py

Use runpod_validate.py for the cheapest live launch/runtime sanity check. Use runpod_corpus_matrix.py only for model-family or corpus coverage after the smoke is green, starting with the smallest scope that answers the question. These are GPU/network checks and do not replace the no-GPU structural gates. Use port check and port convert for import conversion; use the offline approved-record transport to check record bytes and queue payloads.

Report Outputs

Runs return a RunResult with run_id, prompt_id, outputs, metadata_path, and log_path. The same fields are persisted under out/runs/<run_id>/.

Report:

• generated files under the run directory
• out/runs/<run_id>/metadata.json
• prompt_id when available
• relevant vibecomfy logs tail lines if execution failed

Do not report an edit candidate as a run result. A candidate graph from the Comfy app or agentic edit harness becomes a run result only after it is applied or executed through vibecomfy run / runtime APIs.