ComfyHelper

Edit ComfyUI API-format workflow JSON from Python or the command line, then submit it to a running ComfyUI instance.

ComfyHelper is intentionally focused on value overrides: prompts, seeds, sampler settings, dimensions, loaders, LoRAs, and output naming. It does not try to build arbitrary ComfyUI graphs from scratch.

Install

pip install -e ".[dev]"

The package requires Python 3.12 or newer.

Workflow Format

Use ComfyUI's API-format workflow JSON, not the full visual editor workflow format. In ComfyUI, enable developer/API workflow export and save the API JSON.

CLI Usage

Run a workflow and save returned images:

comfyhelper run basic_api.json \
  --positive "a red apple on a white table, photorealistic" \
  --negative "blurry, low quality" \
  --seed 42 \
  --steps 30 \
  --cfg 7.5 \
  --sampler euler \
  --scheduler simple \
  --width 1024 \
  --height 1024 \
  --image input.png \
  --filename-prefix apple_test \
  --output-dir ./output

Submit without waiting:

comfyhelper run basic_api.json --positive "a cat" --no-wait

Use multiple LoRAs. The final workflow will contain exactly these LoRAs, chained in order:

comfyhelper run basic_api.json \
  --lora detail.safetensors \
  --lora style.safetensors \
  --lora-strength 0.8 \
  --lora-strength 0.6

For split-loader workflows:

comfyhelper run workflow.json \
  --diffusion-model flux1-dev.safetensors \
  --clip clip_l.safetensors \
  --clip t5xxl_fp16.safetensors \
  --vae ae.safetensors

Override ControlNet and image scaling nodes:

comfyhelper run workflow.json \
  --controlnet-model sdxl_controlnet_promax.safetensors \
  --controlnet-strength 0.7 \
  --controlnet-start-percent 0 \
  --controlnet-end-percent 0.7 \
  --image-scale-upscale-method nearest-exact \
  --image-scale-megapixels 1.0 \
  --image-scale-resolution-steps 1

Python Usage

from comfyhelper import ComfyClient, Workflow

workflow = Workflow.from_file("basic_api.json")
workflow.set_positive_prompt("a red apple on a white table")
workflow.set_negative_prompt("blurry, low quality")
workflow.set_seed(42)
workflow.set_steps(30)
workflow.set_dimensions(1024, 1024)
workflow.set_loras([
    ("detail.safetensors", 0.8),
    ("style.safetensors", 0.6),
])

client = ComfyClient(host="localhost", port=8188)
result = client.run(workflow)
images = result.download(client)

Supported Setters

General workflow edits:

• set_positive_prompt(text, sampler_id=None)
• set_negative_prompt(text, sampler_id=None)
• set_prompt_node(node_id, text)
• set_node_input(class_type, field, value)
• set_node_input_by_id(node_id, field, value)
• set_seed(seed)
• set_steps(steps)
• set_cfg(cfg)
• set_sampler(sampler_name)
• set_scheduler(scheduler)
• set_denoise(denoise)
• set_dimensions(width, height)
• set_batch_size(batch_size)
• set_filename_prefix(prefix)
• get_load_image_count()
• set_load_image(image)
• set_load_images(images)

Loader edits:

• set_checkpoint(name) for CheckpointLoaderSimple.ckpt_name
• set_diffusion_model(name) for UNETLoader.unet_name
• set_clip(name) for CLIPLoader.clip_name
• set_clips(names) for CLIPLoader, DualCLIPLoader, TripleCLIPLoader, and QuadrupleCLIPLoader
• set_vae(name) for VAELoader.vae_name
• set_controlnet_model(name) for ControlNetLoader.control_net_name
• set_apply_controlnet(strength=None, start_percent=None, end_percent=None) for ControlNetApplyAdvanced
• set_image_scale_to_total_pixels(upscale_method=None, megapixels=None, resolution_steps=None) for ImageScaleToTotalPixels
• set_lora(name, strength=1.0)
• set_loras([(name, strength), ...])

Validation

Use workflow.validate() to get a list of obvious structural issues, or workflow.validate_or_raise() to raise a ValueError. ComfyClient.submit() validates before sending the workflow to ComfyUI.

Validation checks are intentionally lightweight. ComfyUI remains the source of truth for node-specific compatibility.

Notes and Limits

• The first KSampler is the default target for prompt and sampler setters.
• Workflows with multiple samplers can use sampler_id for prompt setters or set_node_input_by_id() for explicit edits.
• set_loras() replaces existing LoraLoader nodes and creates a fresh chain.
• The CLI saves images into ComfyUI subfolders when provided and avoids overwriting existing files by adding numeric suffixes.
• Custom extension nodes can still be edited with set_node_input_by_id().