Cloud Upload Architecture#

comfy-cli provides two distinct upload systems with different endpoints, purposes, and outputs. Confusing them is the most common source of file-staging bugs.

System 1 — comfy upload (transfer command)#

Entry point: comfy_cli/command/transfer.py → execute_upload

Endpoint: POST /upload/image on the ComfyUI server 1

Purpose: Puts files into the server's input/ directory so that ComfyUI nodes (e.g. LoadImage, LoadVideo) can reference them by filename. Works against both local and cloud targets.

Key behaviors:

• Sends a multipart/form-data body with a field named "image" regardless of actual file type 2
• Returns a cloud_name (the server-assigned filename) in data.uploads[0].cloud_name 3
• Safety cap: 2 GB per file 4
• Within a project, prefer comfy assets push — it deduplicates by content hash, records server names in .comfy/assets.lock.json, and lets blueprints reference files as $asset.<path> without manual name tracking 5

Typical usage:

comfy --json upload photo.png --where cloud
# → data.uploads[0].cloud_name is the server-side filename to paste into workflows

System 2 — comfy generate upload (generate API)#

Entry point: comfy_cli/command/generate/upload.py → upload_target

Endpoint: POST /customers/storage → signed PUT URL 6

Purpose: Hosts a reference asset on Comfy's CDN and returns a signed download URL for use as an input to partner-API comfy generate calls (e.g., image-to-video). Not a ComfyUI server upload — the result is a CDN URL, not a server-side filename.

Key behaviors:

• Two-step: POST to /customers/storage with {file_name, content_type, file_hash} → get {upload_url, download_url, existing_file}, then PUT bytes to the signed upload_url 7
• Content-hash deduplication: if existing_file is true, the PUT is skipped and download_url is returned immediately — no re-upload 8
• download_url is a signed URL that expires after 24 hours 9
• Accepts a local file path or a remote http(s):// URL (downloads and re-hosts the remote) 10
• Use --json in scripts — without it the URL may soft-wrap in the terminal 11

Typical usage (I2V pattern):

comfy generate <image-model> --download still.png
comfy generate upload still.png --json # → {url, expires_at}
comfy generate <i2v-model> --image <url> --download clip.mp4

12

Comparison#

Known Limitation: Videos Not Catalogued for Node Selection#

Uploading a video via comfy upload (System 1) does not make it selectable in LoadVideo's input choices on cloud — only pushed images appear in LoadImage's choices 13:

"pushed videos are not yet catalogued for LoadVideo on cloud, so the cross-job video handoff requires local assembly today."

Workaround: For a cross-job video handoff, assemble clips locally rather than relying on a second cloud graph picking up the video by name.

Note: the correct input key for LoadVideo is "file" (not "video") — the wrong key passes client-side validation but fails server-side at input staging 14.

Related Files#

• comfy_cli/command/transfer.py — execute_upload, execute_download
• comfy_cli/command/generate/upload.py — signed-URL upload for generate subcommands
• comfy_cli/fragments.py — PATH_LOADERS table (authoritative input keys per modality)
• comfy_cli/skills/comfy/SKILL.md — operator guidance for file transfer patterns and project asset push