Problem
comfy run --workflow <file> currently only accepts API-format workflow JSON. The validator in comfy_cli/command/run.py::load_api_workflow explicitly rejects UI/save-format files (anything with litegraph's nodes/links keys) and exits with:
Specified workflow does not appear to be an API workflow json file
This is a usability cliff for end users:
- The default "Save" / "Save Workflow" option in the ComfyUI frontend produces UI/litegraph format.
- "Save (API Format)" is hidden behind dev mode in the frontend settings, so most users don't know it exists or that they need it.
- Workflows shared on Civitai, Reddit, in PNG metadata, etc. are almost always in UI/save format.
- The result: users naturally try
comfy run --workflow my-workflow.json with whatever they exported, hit the error, and have no path forward from the CLI.
Proposed change
Have comfy run auto-detect UI/save-format workflows and convert them to API format before POSTing to /prompt, similar to what several ComfyUI MCP servers already do.
Prior art
- SethRobinson/comfyui-workflow-to-api-converter-endpoint — a custom node that reimplements the frontend's "Save (API)" JS logic in Python and exposes it as a
/workflow/convert endpoint on the ComfyUI server. Handles subgraphs (including nested), reroute nodes, bypassed passthrough nodes, combo widget normalization, COMFY_DYNAMICCOMBO_V3, default values from INPUT_TYPES(), and Unicode preservation. Works on workflows up to ~200 KB (Flux, Wan 2.2, etc.).
- lalanikarim/comfyui-mcp / IO-AtelierTech/comfyui-mcp — MCP servers with explicit format detection and
convert_workflow_to_ui / format-aware save_workflow tools.
The Comfy Cloud MCP server explicitly calls this out as a known limitation ("Cannot run saved workflows by ID. ... Saved workflows use the ComfyUI graph format, which requires conversion to API format"), so a shared converter would benefit multiple Comfy-Org tools.
Suggested approach
Two reasonable options, in order of preference:
- Server-side conversion (preferred): if a
/workflow/convert (or equivalent) endpoint is available on the running ComfyUI server, POST the UI workflow there and use the returned API format. This is the most robust because it uses the server's actual node registry, INPUT_TYPES defaults, and handles custom nodes correctly. Falls back to option 2 if the endpoint is missing.
- Client-side conversion: port the frontend's "Save (API Format)" logic (or reuse SethRobinson's implementation) into
comfy_cli. Pros: works against any ComfyUI server. Cons: must keep up with frontend changes (subgraphs, reroutes, dynamic combos, etc.), and can't fully resolve custom-node defaults without /object_info.
A hybrid is fine: query /object_info from the running server for node schemas, and run the conversion locally.
CLI surface
No flag needed for the common case — just have load_api_workflow (or a new load_workflow) detect format and convert transparently, with a log line like:
Detected UI-format workflow, converting to API format via <server endpoint | local converter>...
Optionally add --format {auto,api,ui} for users who want to force a path, and --save-converted <file> to dump the converted API JSON for debugging.
Out of scope (but related)
- Round-trip conversion (API → UI) for users who want to re-edit a workflow they only have in API form.
- Caching converted output by file mtime (Seth's converter does this in his app — could be a follow-up if conversion is expensive).
Problem
comfy run --workflow <file>currently only accepts API-format workflow JSON. The validator incomfy_cli/command/run.py::load_api_workflowexplicitly rejects UI/save-format files (anything with litegraph'snodes/linkskeys) and exits with:This is a usability cliff for end users:
comfy run --workflow my-workflow.jsonwith whatever they exported, hit the error, and have no path forward from the CLI.Proposed change
Have
comfy runauto-detect UI/save-format workflows and convert them to API format before POSTing to/prompt, similar to what several ComfyUI MCP servers already do.Prior art
/workflow/convertendpoint on the ComfyUI server. Handles subgraphs (including nested), reroute nodes, bypassed passthrough nodes, combo widget normalization, COMFY_DYNAMICCOMBO_V3, default values fromINPUT_TYPES(), and Unicode preservation. Works on workflows up to ~200 KB (Flux, Wan 2.2, etc.).convert_workflow_to_ui/ format-awaresave_workflowtools.The Comfy Cloud MCP server explicitly calls this out as a known limitation ("Cannot run saved workflows by ID. ... Saved workflows use the ComfyUI graph format, which requires conversion to API format"), so a shared converter would benefit multiple Comfy-Org tools.
Suggested approach
Two reasonable options, in order of preference:
/workflow/convert(or equivalent) endpoint is available on the running ComfyUI server, POST the UI workflow there and use the returned API format. This is the most robust because it uses the server's actual node registry, INPUT_TYPES defaults, and handles custom nodes correctly. Falls back to option 2 if the endpoint is missing.comfy_cli. Pros: works against any ComfyUI server. Cons: must keep up with frontend changes (subgraphs, reroutes, dynamic combos, etc.), and can't fully resolve custom-node defaults without/object_info.A hybrid is fine: query
/object_infofrom the running server for node schemas, and run the conversion locally.CLI surface
No flag needed for the common case — just have
load_api_workflow(or a newload_workflow) detect format and convert transparently, with a log line like:Optionally add
--format {auto,api,ui}for users who want to force a path, and--save-converted <file>to dump the converted API JSON for debugging.Out of scope (but related)