From 8a9dba092cb0ea64033dd37e5fbc129626247258 Mon Sep 17 00:00:00 2001 From: Vinh Trinh Date: Thu, 5 Nov 2026 02:44:19 -0500 Subject: [PATCH 1/7] feat(skills): comfy-run-on-cloud skill takes a local workflow to Comfy Cloud and hands back its link Builds on #1008. The agent reads the workflow from the running local server, checks it with `comfy workflow check --where cloud --models-dir`, then runs it on Comfy Cloud, an existing build, a swapped copy or a custom build. A model the check cannot prove the same runs on Cloud's copy and is named in the report. It asks by name before every upload and lossy swap: a model goes through `comfy model upload` after a dry run, and a deployment run goes first with `--no-upload`, asks about the files in details.missing[], then reruns with one `--allow-upload ` per approved file. It runs one real job and saves with `comfy workflow save --where cloud`, ending with the folder link, or says there is none for a record-only save. comfy-build points a single-workflow request at the new skill, comfy-build-failures says a missing import needs a way to install it before another cut, and comfy-deploy and comfy-deploy-failures read a deployment with `deploy show` outside a Build folder, since `deploy status` needs one. --- CHANGELOG.md | 22 ++ comfy_cli/skills/__init__.py | 1 + .../skills/comfy-build-failures/SKILL.md | 12 + comfy_cli/skills/comfy-build/SKILL.md | 5 + .../skills/comfy-deploy-failures/SKILL.md | 6 +- comfy_cli/skills/comfy-deploy/SKILL.md | 4 +- .../comfy-run-on-cloud/PROMPT-TEMPLATE.md | 29 ++ comfy_cli/skills/comfy-run-on-cloud/SKILL.md | 311 ++++++++++++++++++ comfy_cli/skills/comfy/SKILL.md | 3 +- comfy_cli/skills/command.py | 7 +- tests/comfy_cli/skills/test_installer.py | 156 +++++++++ 11 files changed, 550 insertions(+), 6 deletions(-) create mode 100644 comfy_cli/skills/comfy-run-on-cloud/PROMPT-TEMPLATE.md create mode 100644 comfy_cli/skills/comfy-run-on-cloud/SKILL.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 526d713d8..7f505eb04 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,28 @@ history. ### Added +- The `comfy-run-on-cloud` agent skill, installed with the other bundled + skills and read with `comfy skills show comfy-run-on-cloud`. It takes one + workflow from a running local ComfyUI (read through the server's + `/api/userdata`, so no folder path is needed) to Comfy Cloud: it checks the + workflow with `comfy workflow check --where cloud --models-dir` (the + install's model folders, so a local model that differs from Cloud's copy + blocks), then runs it on Comfy Cloud as is, on an existing build in the workspace, with a lossless node swap + made on a copy, with a lossy swap the person agreed to, or on a custom build. + A model the check cannot prove the same runs on Cloud's copy and is named in + the report. Every local file upload is asked by name, models go through + `comfy model upload` after a dry run, a deployment run holds its automatic + uploads with `--no-upload` and then uploads only the approved files with + `--allow-upload`, and the agent runs + one real job before it saves with `comfy workflow save --where cloud` and + hands back the folder link (or says there is none for a record-only save). + `comfy_cli/skills/comfy-run-on-cloud/PROMPT-TEMPLATE.md` is the prompt local + ComfyUI's Copy prompt button gives the agent. `comfy-build` points a + single-workflow request at the new skill, `comfy-build-failures` says a + missing import needs a way to install it before another cut, and + `comfy-deploy` and `comfy-deploy-failures` read a deployment with + `deploy show` outside a Build folder, since `deploy status` needs one. + Builds on #1008. - `comfy deploy run --allow-upload ` (repeatable) uploads a local file the deployment lacks only if its hash is listed; any other file fails with `deploy_asset_missing` and is not sent. A file Cloud already holds is reused diff --git a/comfy_cli/skills/__init__.py b/comfy_cli/skills/__init__.py index c813bafdb..1dc1d814d 100644 --- a/comfy_cli/skills/__init__.py +++ b/comfy_cli/skills/__init__.py @@ -49,6 +49,7 @@ ("comfy-build", "comfy-build"), ("comfy-deploy", "comfy-deploy"), ("comfy-custom-nodes", "comfy-custom-nodes"), + ("comfy-run-on-cloud", "comfy-run-on-cloud"), ) diff --git a/comfy_cli/skills/comfy-build-failures/SKILL.md b/comfy_cli/skills/comfy-build-failures/SKILL.md index 304b818bc..477a138cd 100644 --- a/comfy_cli/skills/comfy-build-failures/SKILL.md +++ b/comfy_cli/skills/comfy-build-failures/SKILL.md @@ -159,6 +159,18 @@ cause completely, in one cut. Do not split its edits across cuts, and do not gue at a second cause in the same cut. Before each new cut, tell the user the cause, the exact edit, and which build this is, and wait. +**A missing import needs an installation mechanism before another cut.** Read +the selected pack's verified source and declared requirements, or establish a +supported builder installation path. A `pipDependencies` constraint only pins a +package installed by another mechanism; adding `PyYAML==` does not by +itself install a missing `yaml` import. First verify what will install the +package, then select a compatible constraint if needed. A changed local source +bundle also needs approval for its changed contents and bytes before upload. +When no verified installation mechanism exists, report that blocker and ask for +the missing source or supported installation choice. Do not propose or create a +fresh paid cut merely to try an otherwise unsupported pin, even if the previous +repair plan was approved. + **Read in this order.** 1. `comfy build release show` — **`failureReason` is per target, at diff --git a/comfy_cli/skills/comfy-build/SKILL.md b/comfy_cli/skills/comfy-build/SKILL.md index 9acd5a889..620c83470 100644 --- a/comfy_cli/skills/comfy-build/SKILL.md +++ b/comfy_cli/skills/comfy-build/SKILL.md @@ -106,6 +106,11 @@ the one the situation calls for rather than guessing at its contents: All four converge on the same file, then the same `validate → push → release` tail. +If the goal is one workflow running on Comfy Cloud ("Run on Cloud", or "put this +workflow on Cloud") rather than an environment, read +`comfy skills show comfy-run-on-cloud` first: Comfy Cloud itself or an existing +build may already run it, and a build it needs carries only what that workflow loads. + --- ## Path A — from a ComfyUI install diff --git a/comfy_cli/skills/comfy-deploy-failures/SKILL.md b/comfy_cli/skills/comfy-deploy-failures/SKILL.md index 732511700..ff67fd2fa 100644 --- a/comfy_cli/skills/comfy-deploy-failures/SKILL.md +++ b/comfy_cli/skills/comfy-deploy-failures/SKILL.md @@ -51,10 +51,10 @@ argument you pass. | `deploy_ambiguous_build` | Two or more Builds share the name before the slash | Name the Build by its id, as `/` | | `deploy_forbidden` | The workspace does not permit this | Confirm which workspace is signed in | | `deploy_not_signed_in` | No usable Cloud session or workspace API key, or the key was refused | Replace the key the hint names; otherwise `comfy cloud login` | -| `deploy_server_error` | Control plane unavailable or 5xx | Re-read `status` before retrying, so a retry cannot double-create | -| `deploy_update_replaced` | A watched `up`, `promote` or `rollback` was replaced by a newer update; `details.replacing_release_id` names its release | Follow it with `comfy deploy status --deployment `, or end it with `comfy deploy cancel --deployment ` | +| `deploy_server_error` | Control plane unavailable or 5xx | Re-read `comfy deploy show --deployment ` before retrying, so a retry cannot double-create | +| `deploy_update_replaced` | A watched `up`, `promote` or `rollback` was replaced by a newer update; `details.replacing_release_id` names its release | Read it with `comfy deploy show --deployment `, or end it with `comfy deploy cancel --deployment ` | | `deploy_updates_unavailable` | `promote`, `rollback`, `history`, `cancel` or `events --release` on a deployment with no `revision`, or `cancel` against a deploy service too old for it | `promote` or `rollback`: `up --create` on the release instead. `history`: read `events`. `cancel`: wait for the update to land or fail. `events`: drop `--release`; those events do not say which release made them | -| `deploy_watch_lost` | The watch's reads went unanswered for a minute, or a move by `up`, `promote` or `rollback` did not land within an hour (exit 75); the deployment may still be coming up | `comfy deploy status --deployment --watch`, or after a move `comfy deploy show --deployment ` until it shows no `pendingUpdate`; do not redeploy | +| `deploy_watch_lost` | The watch's reads went unanswered for a minute, or a move by `up`, `promote` or `rollback` did not land within an hour (exit 75); the deployment may still be coming up | Read `comfy deploy show --deployment ` from any folder; watching requires `comfy deploy status --deployment --watch` with this Build's verified spec. After a move, read until no `pendingUpdate`; do not redeploy | | `watch_auth_lost` | A watch's read was refused with a 401 despite session recovery, and a refreshable sign-in remains stored (exit 75); the deployment may still be coming up | Reattach as for `deploy_watch_lost` before considering a new sign-in; do not redeploy | | `deploy_delete_needs_confirm` | `delete` without `--yes` non-interactively | Confirm with the user, then pass `--yes` | diff --git a/comfy_cli/skills/comfy-deploy/SKILL.md b/comfy_cli/skills/comfy-deploy/SKILL.md index 7772bbe32..7d1840ca3 100644 --- a/comfy_cli/skills/comfy-deploy/SKILL.md +++ b/comfy_cli/skills/comfy-deploy/SKILL.md @@ -171,7 +171,9 @@ provisioning". Things to read correctly: - No `progress` at all is an older service, or a status other than the two above. Interrupting the wait leaves the deployment coming up on the service's side; -`comfy deploy status --deployment --watch` attaches again. A deploy API that +read `comfy deploy show --deployment ` from any folder. To watch again, +use `comfy deploy status --deployment --watch` with this Build's +verified spec. A deploy API that stops answering (a 5xx or a dropped connection, as during its own rollout) is retried for about a minute; if it is still down, the wait ends with `deploy_watch_lost` and **exit 75**, not 1. That is not a failed deployment: diff --git a/comfy_cli/skills/comfy-run-on-cloud/PROMPT-TEMPLATE.md b/comfy_cli/skills/comfy-run-on-cloud/PROMPT-TEMPLATE.md new file mode 100644 index 000000000..6578b0690 --- /dev/null +++ b/comfy_cli/skills/comfy-run-on-cloud/PROMPT-TEMPLATE.md @@ -0,0 +1,29 @@ +# The Run on Cloud prompt + +This is the text **Copy prompt** puts on the clipboard in local ComfyUI. The +person pastes it into Claude Code or Codex, and the agent loads the +`comfy-run-on-cloud` skill from it. + +```text +Run my ComfyUI workflow on Comfy Cloud. +If comfy is missing: uv tool install comfy-cli +Read the skill first: comfy skills show comfy-run-on-cloud +Workflow: workflows/.json +ComfyUI: http://127.0.0.1:8188 +``` + +Fill it from the running app: + +- `Workflow:` is the saved workflow's path under the user's data folder, as + the server's `/api/userdata` takes it (`workflows/.json`, subfolders + included). Save the workflow before copying; an unsaved tab has no path. +- `ComfyUI:` is the address the page was loaded from. +- When the server runs with `--multi-user`, add one more line with the user + the page is signed in as, which the agent sends as the `comfy-user` header: + + ```text + ComfyUI user: + ``` + +The prompt names no build, GPU or upload. The skill asks for those in the chat, +only when the workflow needs them. diff --git a/comfy_cli/skills/comfy-run-on-cloud/SKILL.md b/comfy_cli/skills/comfy-run-on-cloud/SKILL.md new file mode 100644 index 000000000..be4b84355 --- /dev/null +++ b/comfy_cli/skills/comfy-run-on-cloud/SKILL.md @@ -0,0 +1,311 @@ +--- +name: comfy-run-on-cloud +description: "Use when someone wants a workflow from their local ComfyUI running on Comfy Cloud, clicked Run on Cloud, or pasted a Run on Cloud prompt. Checks the workflow against Comfy Cloud, uses an existing build or a node swap where Cloud lacks something, runs one real job, saves the workflow to their Cloud workspace and hands back the link that opens it." +--- + +# comfy-run-on-cloud + +One workflow in, one link out. The person wants their workflow running on Comfy +Cloud; how it gets there is your job. Work on copies: never change the person's +original workflow. + +## What the prompt allows, and what needs a yes + +The Run on Cloud prompt is a yes to: + +- reading the workflow and the local server, and checking it against Comfy Cloud; +- running it on Comfy Cloud (each run costs credits); +- lossless changes made on a copy (the table in step 4). + +Each of these needs its own yes in chat, asked before you do it: + +- **uploading any file from this machine**: a model, a LoRA, an input image, + video or audio, or a custom node folder. Ask by file name, one line per file: + path, size, what it is for, where it goes. A yes covers the files you named; a + new or changed file needs a new yes; +- a **lossy** change (step 4); +- a **new build or deployment** (it costs money to build and to keep running); +- stopping, deleting or replacing any existing build, release or deployment. + +Put the questions you have now into one short message. If the person says no to +a file the workflow needs, do not upload it and do not swap in another file: +report "prepared, not run" and say what is missing. + +## 1. Get comfy-cli ready + +- `comfy workflow check --help` and `comfy model upload --help` must both work. + If one fails, upgrade once with the tool that installed comfy-cli + (`uv tool upgrade comfy-cli`). Still failing: tell the person the version + `comfy --version` prints, and stop. +- `comfy --json cloud status`. Not signed in: `comfy cloud login`. Note + `cloud_workspace.id`; every upload and save goes to this workspace. + +## 2. Read the workflow from the local server + +The prompt gives `Workflow: workflows/.json` and the server URL, plus a +`ComfyUI user:` line when the server runs with `--multi-user`. Fetch the file +from the server; you do not need its folder on disk. Encode each `/` in the path +as `%2F`: + +```shell +mkdir -p run-on-cloud/ +curl -sf "/api/userdata/workflows%2F.json" \ + -H "comfy-user: " -o run-on-cloud//original.json +``` + +Leave out the `comfy-user` header when there is no user line. Do all work in +`run-on-cloud//`. If the prompt names no workflow, ask which one. + +Every later comfy command that reads the local server (a `--where local` run) +must reach this same server, not comfy-cli's default of `127.0.0.1:8188`. +Prefix each one with the prompt's address: `COMFY_LOCAL_URL= comfy ...`. + +## 3. Check it against Comfy Cloud + +Find the install's model folders first, so the check can compare the person's +files with Cloud's copies. `comfy --json which` names the install: for Comfy +Desktop, each `desktop.model_roots[].path`; otherwise `/models`. +Pass each folder that exists as its own `--models-dir`: + +```shell +comfy --json which +comfy --json workflow check run-on-cloud//original.json --where cloud \ + --models-dir [--models-dir ] +``` + +Without `--models-dir` the check cannot see a local file, so a model the person +has in a different version than Cloud's never shows up as `different_file`. +`which` names the install comfy-cli tracks, which may not be the one serving +``. If the check finds no `local_paths` for models the workflow loads, +ask the person where that server keeps its models and pass that folder instead. + +`data.verdict` decides the next step: + +| verdict | meaning | next | +|---|---|---| +| `covered` | Comfy Cloud has every node type and model | Run `original.json` on Comfy Cloud (step 6) | +| `covered_with_remaps` | Runs once its models point at Cloud's copies; `models[]` lists each remap | Write the remapped copy (below), then treat it as `covered` or `covered_needs_check` | +| `covered_needs_check` | Nothing is missing, but a model is not proven the same file as Cloud's copy | Run on Cloud's copy without asking (step 6); name those models in the report | +| `needs_build` | A node type or model is missing, or the person's model differs from Cloud's; `blocking[]` lists each | Step 4 | + +A model that is not proven the same is any `models[]` row whose `identity` is +`unverified`. Cloud's library models carry no content hash, so a workflow on +stock models lands here at best; that is expected, not a reason to ask. A model +proven different (`source` `yours`, `identity` `different`) is never run on +Cloud's copy: it is already in `blocking[]` as `different_file`. + +A remap is lossless. Write it without asking, with the same `--models-dir` +folders: + +```shell +comfy --json workflow check run-on-cloud//original.json --where cloud \ + --models-dir --apply-remaps --out run-on-cloud//cloud.json +``` + +Run `cloud.json` from here on. If any of its `models[]` rows is still +`unverified`, it is the `covered_needs_check` case: run it, and name those +models in the report. + +## 4. Something is missing: pick the route in this order + +When `blocking[]` lists only models, keep Comfy Cloud: upload each one (step 5), +then check the copy again. A model item's `reason` says why: `not_on_cloud` +(Cloud has no file of that name), `ambiguous` (Cloud has several; `models[]` +lists the `candidates`, and picking one is a lossy swap unless the person's file +is proven the same), or `different_file` (Cloud's file of that name differs from +the person's, so theirs is uploaded). When it lists a node type, go down this list and stop +at the first that works: + +1. **An existing build in the workspace.** `comfy --json deploy ls --workspace`, + then for each running deployment `comfy --json deploy show --deployment ` + for the release it serves. Read that release with + `comfy --json build release manifest `: its `customNodes` and + `models` are what the deployment runs. Judge packs and models from this one + manifest, never from `build show`: a Build's definition can change after the + release was cut, and the deployment keeps the old release. It fits when the + served release has every pack and model the workflow needs. Keep the workflow + unchanged and run it there (step 6). A build with no running deployment needs + a yes to start one (`comfy-deploy`). +2. **A lossless node swap**, made on a copy without asking. +3. **A lossy swap**, asked first. A yes runs the copy on Comfy Cloud. A no goes + to a custom build. +4. **A custom build.** Read `comfy skills show comfy-build` and `comfy skills + show comfy-deploy`, and follow them. Build only what this workflow loads: + `comfy --json build init --name --from-workflow `. Before + building, show the plan and get a yes: what it uploads, the GPU and region + (cheapest that fits first, from `comfy --json deploy refs compute`), the + costs, and `--min 0 --max 1` workers. + +| kind | what counts | what you do | +|---|---|---| +| Lossless | A remap from the check; a utility node swapped for the core node that computes the same thing (math, string concat, a LoRA stack as chained `LoraLoaderModelOnly` at the same strengths, a pipe node as direct links); removing a node no output depends on | Do it on a copy and list it in the report | +| Lossy | Anything else that changes what is generated: another model, LoRA, VAE, ControlNet, upscaler or embedding; dropping a LoRA or a node that touches pixels; another implementation of the same job | Ask first (below) | +| Not swappable | A node that does the core work and has no core equivalent on Cloud | Existing build or custom build | + +**Asking about a lossy swap.** One message: each swap as `original -> replacement` +and how the output may change; then two choices. **Swap**: runs on Comfy Cloud, +nothing to build, output may differ. **Keep the original**: a custom build, with +its costs. Offer only replacements from the same model family, taken from +`comfy --json nodes show --where cloud --all-choices`. + +**Check every changed copy before running it.** Pack versions move widget values: + +```shell +comfy --json run --workflow --print-prompt --where cloud > preview.json +jq '.data.prompt' preview.json > api.json +comfy --json workflow validate --workflow api.json --where cloud +``` + +Fix a widget by name with `comfy --json workflow set-widget +. --where cloud`, only to a value that keeps the saved +behavior. + +## 5. Uploads, each asked by name + +**A model** from a `blocking[]` item. The item names the file: `filename`, +`folder` (the ComfyUI models folder, or null when unknown), `url` (where the +workflow says it downloads from, or null) and `local_paths` (copies found under +`--models-dir`). No `local_paths`: say the file is not on this machine, give the +`url` if there is one, and do not upload anything for it. Several `local_paths`: +ask which one. + +The dry run sends no file; it hashes the file here and reads the library: + +```shell +comfy --json model list-folders --where cloud +comfy --json model upload --type --workspace --where cloud --dry-run +``` + +`` is the item's `folder` when `model list-folders` lists it; otherwise +pick the folder the loader reads from and say so. If the dry run says +`already_present`, Comfy Cloud has these exact bytes under that name: nothing +needs uploading or asking; use its `loader_path`. Otherwise ask by `filename`, +with the dry run's path, `size`, `sha256` and destination folder. After the yes: + +```shell +comfy --json model upload --type --workspace --where cloud \ + --yes --expected-sha256 +``` + +Set the loader on the copy to the returned `loader_path`, then run the check on +the copy again. When it fails, nothing ran on Comfy Cloud yet: + +| error | what to do | +|---|---| +| `model_upload_needs_confirm` | `--yes` was missing. Ask, if you have not, then run it with `--yes --expected-sha256` | +| `asset_upload_wrong_workspace` | This sign-in uploads into another workspace (`details.current_workspace`). Nothing was sent. Tell the person; upload only after they sign in to the approved one (`comfy cloud login`) or approve the current one | +| `asset_upload_invalid`, `file_changed` | The file changed since the approved dry run. Run the dry run again and ask again with the new `sha256` | +| `asset_upload_invalid`, `name_in_use` or `name_unverified` | The folder already has (or may have) another file of this name, and uploading would change what the name loads for the whole workspace. Copy the file under a new name into `run-on-cloud//`, then dry run and ask again with that name | +| `asset_upload_invalid`, `bad_expected_sha256` | Pass the 64-hex `sha256` from the dry run | +| `asset_upload_invalid`, other reasons | The message names the file or `--type` problem; fix it, or report it as what blocks the run | +| `asset_upload_unverified` | The file is stored, but Cloud's hash of it does not match or could not be read. Do not run a workflow that loads it; report it, with `details.asset_id` | + +**An input file** (image, video, audio) a loader names: fetch it from the local +server, then upload it after the yes: + +```shell +curl -sf "/api/view?filename=&subfolder=&type=input" \ + -H "comfy-user: " -o run-on-cloud//inputs/ +comfy --json upload run-on-cloud//inputs/ --where cloud +``` + +Set the loader on the copy to the returned `uploads[].cloud_name`. + +## 6. Run one real job + +Never call it working before a real job succeeds. + +- **Comfy Cloud:** + `comfy --json run --workflow --where cloud --wait`, then + `comfy --json download --where cloud --out-dir run-on-cloud//outputs`. +- **A deployment** (existing or custom build): first read + `comfy --json deploy logs --deployment `; `data.comfyuiLog` must show no + `IMPORT FAILED` for a pack the workflow uses. Make the API file against the + local server, which has the packs: + `COMFY_LOCAL_URL= comfy --json run --workflow --print-prompt --where local`, + `.data.prompt` into `api.json`. + + `deploy run` sends local files on its own. Any string input in `api.json` + with a file extension can match a file, whatever the node type, so a custom + node's text field can too. When two folders hold a file of the same name, it + picks by its own order, which may not be the one you expect. So do not build + the list yourself: get it from `deploy run`. Run it first with `--no-upload`, + which reuses files the deployment already has and sends none: + + ```shell + comfy --json deploy run --deployment --workflow api.json --no-upload \ + --wait --output-dir run-on-cloud//outputs + ``` + + If the deployment has every file, it runs and nothing was sent. Otherwise it + fails with `deploy_asset_missing` before it submits a job. + `details.missing[]` is the exact upload plan: one entry per file, with + `local_path` (the full path it picked), `bytes` and `hash`. Ask about every + entry in one message, by name, with its `local_path` and size (step 5's + rule). On a no, report "prepared, not run". After a yes that covers every + entry, run the same command from the same folder, with `--no-upload` replaced + by one `--allow-upload ` per approved file: + + ```shell + comfy --json deploy run --deployment --workflow api.json \ + --allow-upload --allow-upload \ + --wait --output-dir run-on-cloud//outputs + ``` + + It uploads only files with those hashes. It hashes a private copy of each + file it uploads and sends that copy, so a file that changes meanwhile is not + sent. + After the run, `data.assets.files[]` names each local file it read; report + them. + + If either run fails with `deploy_asset_missing`, read its `details`: + + - `details.missing[]` is there: a file differs from the approved plan + (another file was picked, or one changed). Nothing outside the plan was + sent. Ask again about the new `details.missing[]`; never pass a hash + nobody approved. + - `details.server_code` is `missing_asset`: the workflow names an asset + already on the deployment's side that this account cannot reach. No local + file is involved, so there is nothing to approve or upload. Report that + asset as unreachable, and the run as "prepared, not run". + +Keep the job id. On a timeout, watch the same job; never submit a second paid job +to recover a download. Run comfy commands one at a time. + +## 7. Save it, then hand back the link + +Save the file that ran (the copy, if you changed one): + +```shell +comfy --json workflow save --name --where cloud +comfy --json workflow save --name --where cloud --deployment # ran on a deployment +``` + +It saves into a new folder in the Cloud Workflows sidebar and never replaces a +file. `data.url` opens that folder in the person's workspace: +`?workspace=&workflows=&deployment=`. If `data.url` +is missing, the save is a record only: nothing was added to the Workflows +sidebar and there is no link. Say that plainly, give `data.workflow_id`, and do +not point them at a sidebar entry. Then read `data.warnings[]` for the reason: + +- `api_format_saved_as_record`: sidebar saving is on, but the file is in API + format, which the sidebar cannot open. Save the editor-format file instead + (the copy, not `api.json`) to get a folder and a link. +- no warning: the workspace saves workflows as records only. Sidebar saving is + off, or its setting could not be read. + +## Report + +Lead with the state: ran, or "prepared, not run" and what blocks it. Then: + +- the route: Comfy Cloud, an existing deployment, or a custom build; +- each change made to the copy, and each lossy swap they approved; +- the files uploaded; +- each model that ran on Cloud's copy unproven (`identity` `unverified`), by + name, with one line: the output may differ if their file is another version; +- the job id and where the outputs are on disk; +- for a deployment: its id, GPU, region, worker bounds, cost, and + `comfy deploy stop --deployment ` to stop the billing. + +End with the `data.url` link, or, for a record-only save, the line saying there +is no link. diff --git a/comfy_cli/skills/comfy/SKILL.md b/comfy_cli/skills/comfy/SKILL.md index 22b4f724f..218de59ec 100644 --- a/comfy_cli/skills/comfy/SKILL.md +++ b/comfy_cli/skills/comfy/SKILL.md @@ -20,7 +20,8 @@ know what exists, and reach for the right one rather than improvising its job:** `comfy-director` (multi-shot narrative video — story, continuity, conform), `comfy-build` (build a custom ComfyUI environment on the developer platform), `comfy-deploy` (run a build release as a serverless deployment, and stop it -costing money), `comfy-custom-nodes` (write or fix a custom node pack — preferred V3, +costing money), `comfy-run-on-cloud` (get one workflow from local ComfyUI running +on Comfy Cloud and hand back its link), `comfy-custom-nodes` (write or fix a custom node pack — preferred V3, compatible V1, reference routing, widgets, validation and restart/discovery), `comfy-debug` (any failed job: error code → fix), `comfy-relay` (surface a workflow/result in chat, never leave it in /tmp). When a task spans several, load them up front instead of discovering the gap mid-render. diff --git a/comfy_cli/skills/command.py b/comfy_cli/skills/command.py index 4558fde62..a3da37e6d 100644 --- a/comfy_cli/skills/command.py +++ b/comfy_cli/skills/command.py @@ -4,7 +4,7 @@ agent on the machine how to call ``comfy`` natively. One file per skill, three targets, zero protocol. -Bundled skills (6 total) — see ``comfy skills list`` for descriptions: +Bundled skills — see ``comfy skills list`` for descriptions: - ``comfy`` — the consolidated driver skill (command surface, output contract, routing, discovery, execution, @@ -18,6 +18,11 @@ - ``comfy-deploy`` — running a Build release as a serverless deployment: compute choice, worker bounds, submitting workflows, and what keeps costing money + - ``comfy-custom-nodes`` — writing or fixing a custom node pack + - ``comfy-run-on-cloud`` — one local workflow onto Comfy Cloud: Comfy Cloud + itself first, then an existing build, then a node + swap, then a custom build; ends with the saved + workflow's link Reference skills (``REFERENCE_SKILLS``) are the other half: ``show`` resolves them and no default install writes them, so a parent skill can cite one by name diff --git a/tests/comfy_cli/skills/test_installer.py b/tests/comfy_cli/skills/test_installer.py index b04ddb104..9cf25f0db 100644 --- a/tests/comfy_cli/skills/test_installer.py +++ b/tests/comfy_cli/skills/test_installer.py @@ -56,6 +56,7 @@ def test_bundles_expected_skills(): assert "comfy-director" in names assert "comfy-build" in names assert "comfy-deploy" in names + assert "comfy-run-on-cloud" in names def test_bundled_skills_have_required_frontmatter(): @@ -491,6 +492,161 @@ def test_build_and_deploy_skills_hand_off_to_each_other(): assert "comfy-build" in skill_content("comfy-deploy"), "comfy-deploy should point back at comfy-build" +def test_run_on_cloud_skill_follows_the_check_route(): + """The route starts at `workflow check --where cloud`, reads the workflow + from the running server, gates model uploads through `model upload`, and + ends at the `workflow save` link. `test_no_mentions_of_nonexistent_commands` + resolves each command against the live Typer tree.""" + text = skill_content("comfy-run-on-cloud") + for needle in ( + "comfy --json workflow check", + "--where cloud", + "--apply-remaps --out", + "--models-dir", + "comfy --json which", + "local_paths", + "comfy --json model upload", + "--expected-sha256", + "comfy --json workflow save", + "data.url", + "/api/userdata/workflows%2F", + "comfy-user", + ): + assert needle in text, f"comfy-run-on-cloud skill should mention {needle}" + for verdict in ("covered", "covered_with_remaps", "covered_needs_check", "needs_build"): + assert f"`{verdict}`" in text, f"comfy-run-on-cloud skill should handle the {verdict} verdict" + + +def test_run_on_cloud_skill_runs_unproven_models_on_clouds_copy_and_names_them(): + """Cloud's library models carry no content hash, so `covered_needs_check` is + the usual verdict for stock models: run without asking, and name each + unproven model in the report. A model proven different blocks instead.""" + text = " ".join(skill_content("comfy-run-on-cloud").split()) + assert "Run on Cloud's copy without asking" in text + assert "ran on Cloud's copy unproven" in text + assert "`different_file`" in text + assert "Ask: use Cloud's copy" not in text + + +def test_run_on_cloud_skill_keeps_the_prompts_server_for_local_commands(): + """A server on another port than 8188 must be the one `--where local` reads.""" + text = skill_content("comfy-run-on-cloud") + assert "COMFY_LOCAL_URL= comfy --json run" in text + assert "--where local" in text + + +def test_run_on_cloud_skill_judges_a_deployment_by_its_served_release(): + """A Build's definition can change after its release was cut, so packs and + models both come from the served release's manifest.""" + text = " ".join(skill_content("comfy-run-on-cloud").split()) + assert "comfy --json build release manifest " in text + assert "`customNodes` and `models`" in text + assert "comfy --json build show --id" not in text + + +def test_run_on_cloud_skill_holds_deployment_uploads_until_asked(): + """`deploy run` uploads scanner-found files on its own, and with two asset + folders holding a `portrait.png` each it picks one by its own order. So the + skill asks about the scanner's own plan (`details.missing[]` from a + `--no-upload` run, by full path), and the retry may upload only the approved + hashes. A list the skill builds itself from the tracked workspace could name + one `portrait.png` while the run sends the other.""" + text = " ".join(skill_content("comfy-run-on-cloud").split()) + assert "--no-upload" in text + assert "deploy_asset_missing" in text + assert "`details.missing[]` is the exact upload plan" in text + assert "`local_path` (the full path it picked)" in text + assert "--allow-upload " in text + assert "never pass a hash nobody approved" in text + assert "It hashes a private copy of each file it uploads and sends that copy" in text + assert "data.assets.files[]" in text + # The old self-built list, from the tracked workspace only, is gone. + assert "jq -r '[.[].inputs" not in text + assert "Run without `--no-upload` only after" not in text + + +def test_run_on_cloud_skill_asks_again_only_when_there_is_a_local_plan(): + """`deploy_asset_missing` also covers a remote asset the account cannot + reach (`details.server_code` `missing_asset`, with no `details.missing[]`). + Asking again about local files is only for a refusal that lists them.""" + text = " ".join(skill_content("comfy-run-on-cloud").split()) + assert "`details.missing[]` is there: a file differs from the approved plan" in text + assert "`details.server_code` is `missing_asset`" in text + assert "Report that asset as unreachable" in text + + +def test_run_on_cloud_skill_reads_the_save_warning_for_a_missing_link(): + """An API-format file saved with sidebar saving on gets no link either; its + warning says so, so the skill does not blame the workspace setting.""" + text = " ".join(skill_content("comfy-run-on-cloud").split()) + assert "data.warnings[]" in text + assert "`api_format_saved_as_record`: sidebar saving is on" in text + assert "no warning: the workspace saves workflows as records only" in text + + +def test_run_on_cloud_skill_handles_every_model_upload_outcome(): + text = skill_content("comfy-run-on-cloud") + for needle in ( + "already_present", + "model_upload_needs_confirm", + "asset_upload_wrong_workspace", + "asset_upload_unverified", + "asset_upload_invalid", + "file_changed", + "name_in_use", + "name_unverified", + "bad_expected_sha256", + ): + assert needle in text, f"comfy-run-on-cloud skill should handle {needle}" + + +def test_run_on_cloud_skill_says_a_record_only_save_has_no_link(): + """A record-only save adds nothing to the Workflows sidebar.""" + text = " ".join(skill_content("comfy-run-on-cloud").split()) + assert "records only" in text + assert "there is no link" in text + assert "then Workflows, then" not in text + + +def test_run_on_cloud_skill_drops_the_later_milestone_links(): + """Saved-file ids, `workflow ui` and `deploy ui` links are not part of this + route, and `build inventory --cloud` gave way to `workflow check`.""" + text = skill_content("comfy-run-on-cloud") + for gone in ("saved_file_id", "workflow ui", "deploy ui", "build inventory"): + assert gone not in text, f"comfy-run-on-cloud skill should not mention {gone}" + + +def test_run_on_cloud_skill_asks_before_every_upload_and_lossy_swap(): + text = " ".join(skill_content("comfy-run-on-cloud").split()) + assert "uploading any file from this machine" in text + assert "Ask by file name" in text + assert "A lossy swap**, asked first" in text + + +def test_run_on_cloud_prompt_template_loads_the_skill(): + """The prompt "Copy prompt" puts on the clipboard has to name a skill `show` + resolves, and carry the lines the skill reads.""" + import comfy_cli.skills as skills_pkg + + template = (Path(skills_pkg.__file__).parent / "comfy-run-on-cloud" / "PROMPT-TEMPLATE.md").read_text( + encoding="utf-8" + ) + for line in ( + "Run my ComfyUI workflow on Comfy Cloud.", + "If comfy is missing: uv tool install comfy-cli", + "Read the skill first: comfy skills show comfy-run-on-cloud", + "Workflow: workflows/.json", + "ComfyUI: http://127.0.0.1:8188", + "ComfyUI user: ", + ): + assert line in template, f"prompt template should carry {line!r}" + assert "comfy-run-on-cloud" in readable_skill_names() + + +def test_build_skill_points_a_single_workflow_at_run_on_cloud(): + assert "comfy skills show comfy-run-on-cloud" in skill_content("comfy-build") + + def test_skill_content_rejects_unknown_name(): with pytest.raises(ValueError) as exc: skill_content("not-a-real-skill") From 30fcb1b4370aa4d2a1d67fc6a339d9a61fc11ab8 Mon Sep 17 00:00:00 2001 From: Vinh Trinh Date: Thu, 5 Nov 2026 03:37:50 -0500 Subject: [PATCH 2/7] docs(skills): a null loader_path from model upload blocks the run --- comfy_cli/skills/comfy-run-on-cloud/SKILL.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/comfy_cli/skills/comfy-run-on-cloud/SKILL.md b/comfy_cli/skills/comfy-run-on-cloud/SKILL.md index be4b84355..0d2a99ae8 100644 --- a/comfy_cli/skills/comfy-run-on-cloud/SKILL.md +++ b/comfy_cli/skills/comfy-run-on-cloud/SKILL.md @@ -188,7 +188,9 @@ comfy --json model upload --type --workspace --wh ``` Set the loader on the copy to the returned `loader_path`, then run the check on -the copy again. When it fails, nothing ran on Comfy Cloud yet: +the copy again. A null `loader_path` (after an upload or on `already_present`) +means Comfy Cloud gave no loader value for that name: do not put the file name +in its place; report the model as what blocks the run. When it fails, nothing ran on Comfy Cloud yet: | error | what to do | |---|---| From cae952bbd975db2a908117a0e1d694312cb0098e Mon Sep 17 00:00:00 2001 From: Vinh Trinh Date: Thu, 5 Nov 2026 03:51:47 -0500 Subject: [PATCH 3/7] docs(skills): a remap the copy could not apply blocks the run --- comfy_cli/skills/comfy-run-on-cloud/SKILL.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/comfy_cli/skills/comfy-run-on-cloud/SKILL.md b/comfy_cli/skills/comfy-run-on-cloud/SKILL.md index 0d2a99ae8..7b3c8f1f5 100644 --- a/comfy_cli/skills/comfy-run-on-cloud/SKILL.md +++ b/comfy_cli/skills/comfy-run-on-cloud/SKILL.md @@ -104,7 +104,9 @@ comfy --json workflow check run-on-cloud//original.json --where cloud \ Run `cloud.json` from here on. If any of its `models[]` rows is still `unverified`, it is the `covered_needs_check` case: run it, and name those -models in the report. +models in the report. A `remap_not_applied` warning means `cloud.json` still +names the local file on that node: do not run it; report that node and model +as what blocks the run. ## 4. Something is missing: pick the route in this order From 7f00ecf1d80fc30a750f744eb1b77a2bb462c1dc Mon Sep 17 00:00:00 2001 From: Vinh Trinh Date: Thu, 5 Nov 2026 05:23:21 -0500 Subject: [PATCH 4/7] docs(skills): fetch workflows and inputs with any name into a folder that exists --- comfy_cli/skills/comfy-run-on-cloud/SKILL.md | 47 +++++++++++--------- tests/comfy_cli/skills/test_installer.py | 12 +++++ 2 files changed, 39 insertions(+), 20 deletions(-) diff --git a/comfy_cli/skills/comfy-run-on-cloud/SKILL.md b/comfy_cli/skills/comfy-run-on-cloud/SKILL.md index 7b3c8f1f5..ef9758174 100644 --- a/comfy_cli/skills/comfy-run-on-cloud/SKILL.md +++ b/comfy_cli/skills/comfy-run-on-cloud/SKILL.md @@ -44,17 +44,23 @@ report "prepared, not run" and say what is missing. The prompt gives `Workflow: workflows/.json` and the server URL, plus a `ComfyUI user:` line when the server runs with `--multi-user`. Fetch the file -from the server; you do not need its folder on disk. Encode each `/` in the path -as `%2F`: +from the server; you do not need its folder on disk. In the URL, percent-encode +the path after `workflows/`: each `/` as `%2F`, a space as `%20`, and every +other character outside letters, digits, `-`, `_` and `.` the same way. + +Do all work in one folder, written `` below: `run-on-cloud/` plus the +workflow's name with every character other than a letter, digit, `-` or `_` +turned into `-` (`My flow (2)` gives `run-on-cloud/My-flow--2-`). Quote every +path in the commands. ```shell -mkdir -p run-on-cloud/ -curl -sf "/api/userdata/workflows%2F.json" \ - -H "comfy-user: " -o run-on-cloud//original.json +mkdir -p "/inputs" +curl -sf "/api/userdata/workflows%2F.json" \ + -H "comfy-user: " -o "/original.json" ``` -Leave out the `comfy-user` header when there is no user line. Do all work in -`run-on-cloud//`. If the prompt names no workflow, ask which one. +Leave out the `comfy-user` header when there is no user line. If the prompt +names no workflow, ask which one. Every later comfy command that reads the local server (a `--where local` run) must reach this same server, not comfy-cli's default of `127.0.0.1:8188`. @@ -69,8 +75,8 @@ Pass each folder that exists as its own `--models-dir`: ```shell comfy --json which -comfy --json workflow check run-on-cloud//original.json --where cloud \ - --models-dir [--models-dir ] +comfy --json workflow check "/original.json" --where cloud \ + --models-dir "" [--models-dir ""] ``` Without `--models-dir` the check cannot see a local file, so a model the person @@ -98,8 +104,8 @@ A remap is lossless. Write it without asking, with the same `--models-dir` folders: ```shell -comfy --json workflow check run-on-cloud//original.json --where cloud \ - --models-dir --apply-remaps --out run-on-cloud//cloud.json +comfy --json workflow check "/original.json" --where cloud \ + --models-dir "" --apply-remaps --out "/cloud.json" ``` Run `cloud.json` from here on. If any of its `models[]` rows is still @@ -199,7 +205,7 @@ in its place; report the model as what blocks the run. When it fails, nothing ra | `model_upload_needs_confirm` | `--yes` was missing. Ask, if you have not, then run it with `--yes --expected-sha256` | | `asset_upload_wrong_workspace` | This sign-in uploads into another workspace (`details.current_workspace`). Nothing was sent. Tell the person; upload only after they sign in to the approved one (`comfy cloud login`) or approve the current one | | `asset_upload_invalid`, `file_changed` | The file changed since the approved dry run. Run the dry run again and ask again with the new `sha256` | -| `asset_upload_invalid`, `name_in_use` or `name_unverified` | The folder already has (or may have) another file of this name, and uploading would change what the name loads for the whole workspace. Copy the file under a new name into `run-on-cloud//`, then dry run and ask again with that name | +| `asset_upload_invalid`, `name_in_use` or `name_unverified` | The folder already has (or may have) another file of this name, and uploading would change what the name loads for the whole workspace. Copy the file under a new name into `/`, then dry run and ask again with that name | | `asset_upload_invalid`, `bad_expected_sha256` | Pass the 64-hex `sha256` from the dry run | | `asset_upload_invalid`, other reasons | The message names the file or `--type` problem; fix it, or report it as what blocks the run | | `asset_upload_unverified` | The file is stored, but Cloud's hash of it does not match or could not be read. Do not run a workflow that loads it; report it, with `details.asset_id` | @@ -208,9 +214,10 @@ in its place; report the model as what blocks the run. When it fails, nothing ra server, then upload it after the yes: ```shell -curl -sf "/api/view?filename=&subfolder=&type=input" \ - -H "comfy-user: " -o run-on-cloud//inputs/ -comfy --json upload run-on-cloud//inputs/ --where cloud +curl -sfG "/api/view" --data-urlencode "filename=" \ + --data-urlencode "subfolder=" --data-urlencode "type=input" \ + -H "comfy-user: " -o "/inputs/" +comfy --json upload "/inputs/" --where cloud ``` Set the loader on the copy to the returned `uploads[].cloud_name`. @@ -221,7 +228,7 @@ Never call it working before a real job succeeds. - **Comfy Cloud:** `comfy --json run --workflow --where cloud --wait`, then - `comfy --json download --where cloud --out-dir run-on-cloud//outputs`. + `comfy --json download --where cloud --out-dir "/outputs"`. - **A deployment** (existing or custom build): first read `comfy --json deploy logs --deployment `; `data.comfyuiLog` must show no `IMPORT FAILED` for a pack the workflow uses. Make the API file against the @@ -238,7 +245,7 @@ Never call it working before a real job succeeds. ```shell comfy --json deploy run --deployment --workflow api.json --no-upload \ - --wait --output-dir run-on-cloud//outputs + --wait --output-dir "/outputs" ``` If the deployment has every file, it runs and nothing was sent. Otherwise it @@ -253,7 +260,7 @@ Never call it working before a real job succeeds. ```shell comfy --json deploy run --deployment --workflow api.json \ --allow-upload --allow-upload \ - --wait --output-dir run-on-cloud//outputs + --wait --output-dir "/outputs" ``` It uploads only files with those hashes. It hashes a private copy of each @@ -281,8 +288,8 @@ to recover a download. Run comfy commands one at a time. Save the file that ran (the copy, if you changed one): ```shell -comfy --json workflow save --name --where cloud -comfy --json workflow save --name --where cloud --deployment # ran on a deployment +comfy --json workflow save --name "" --where cloud +comfy --json workflow save --name "" --where cloud --deployment # ran on a deployment ``` It saves into a new folder in the Cloud Workflows sidebar and never replaces a diff --git a/tests/comfy_cli/skills/test_installer.py b/tests/comfy_cli/skills/test_installer.py index 9cf25f0db..5e473128a 100644 --- a/tests/comfy_cli/skills/test_installer.py +++ b/tests/comfy_cli/skills/test_installer.py @@ -1409,3 +1409,15 @@ def test_agent_permissions_skill_names_every_permanently_refused_host(): assert len(rows) == 1, "expected exactly one 'never request this host' row in the blocked-by table" for host in _REFUSED_HOSTS: assert host in rows[0], f"the row should name the refused host {host}" + + +def test_run_on_cloud_skill_fetches_files_with_any_name(): + """A workflow or input whose name has a space, `#` or `&` still downloads + into a folder that exists: the query is URL-encoded, the working folder + name is made safe and created with its `inputs` folder, and paths are quoted.""" + text = " ".join(skill_content("comfy-run-on-cloud").split()) + assert 'mkdir -p "/inputs"' in text + assert '--data-urlencode "filename="' in text + assert '--data-urlencode "subfolder="' in text + assert "a space as `%20`" in text + assert "run-on-cloud/" not in text From 5ad5f6128ce6baa29f2ee09d2ff7a08a42e6d95c Mon Sep 17 00:00:00 2001 From: Vinh Trinh Date: Thu, 5 Nov 2026 05:32:16 -0500 Subject: [PATCH 5/7] docs(skills): confirm the server is ComfyUI, ask about models only the server has, wire swaps by slot name A staging run of comfy-run-on-cloud found four gaps: - another program on the prompt's port answered every path with 200, so the fetch wrote its text as the workflow; the skill now checks system_stats first; - a model on neither the disk nor the server still made the agent ask where the models are; it now asks only when the server lists the file; - a swap had no recipe, and wiring by slot number crosses INT and FLOAT on the core math node; it now names slots; - preview.json and api.json were written outside the work folder. --- comfy_cli/skills/comfy-run-on-cloud/SKILL.md | 39 +++++++++++++++----- tests/comfy_cli/skills/test_installer.py | 16 ++++++++ 2 files changed, 45 insertions(+), 10 deletions(-) diff --git a/comfy_cli/skills/comfy-run-on-cloud/SKILL.md b/comfy_cli/skills/comfy-run-on-cloud/SKILL.md index ef9758174..c50876064 100644 --- a/comfy_cli/skills/comfy-run-on-cloud/SKILL.md +++ b/comfy_cli/skills/comfy-run-on-cloud/SKILL.md @@ -53,6 +53,12 @@ workflow's name with every character other than a letter, digit, `-` or `_` turned into `-` (`My flow (2)` gives `run-on-cloud/My-flow--2-`). Quote every path in the commands. +First make sure the address is ComfyUI: `curl -sf "/api/system_stats"` +must answer JSON with `system.comfyui_version`. Anything else (no answer, a web +page, plain text) means another program holds that port: stop, and tell the +person the address does not answer as ComfyUI. Never run the check on what such +an address returns. + ```shell mkdir -p "/inputs" curl -sf "/api/userdata/workflows%2F.json" \ @@ -82,8 +88,12 @@ comfy --json workflow check "/original.json" --where cloud \ Without `--models-dir` the check cannot see a local file, so a model the person has in a different version than Cloud's never shows up as `different_file`. `which` names the install comfy-cli tracks, which may not be the one serving -``. If the check finds no `local_paths` for models the workflow loads, -ask the person where that server keeps its models and pass that folder instead. +``. For a model with no `local_paths`, ask the server whether it has the +file: `curl -sf "/api/models/"` lists the file names it loads +from that folder. Listed there: the `--models-dir` folders are the wrong ones; +ask the person where that server keeps its models and check again with that +folder. Not listed: the file is not on this machine either, so there is nothing +to ask; go on with the verdict. `data.verdict` decides the next step: @@ -134,7 +144,7 @@ at the first that works: served release has every pack and model the workflow needs. Keep the workflow unchanged and run it there (step 6). A build with no running deployment needs a yes to start one (`comfy-deploy`). -2. **A lossless node swap**, made on a copy without asking. +2. **A lossless node swap**, made on a copy without asking (below). 3. **A lossy swap**, asked first. A yes runs the copy on Comfy Cloud. A no goes to a custom build. 4. **A custom build.** Read `comfy skills show comfy-build` and `comfy skills @@ -150,6 +160,15 @@ at the first that works: | Lossy | Anything else that changes what is generated: another model, LoRA, VAE, ControlNet, upscaler or embedding; dropping a LoRA or a node that touches pixels; another implementation of the same job | Ask first (below) | | Not swappable | A node that does the core work and has no core equivalent on Cloud | Existing build or custom build | +**Making a swap.** Copy the workflow to `"/cloud.json"` (or edit +`cloud.json` if the remap already wrote it) and run every edit on that copy with +`--where cloud`: `comfy --json workflow add-node`, then `workflow connect` for +each link, `workflow set-widget` for each value, and `workflow delete-nodes` for +the nodes it replaces. Name slots in `connect`, never their numbers +(`.INT`, not `.0`): the core node may list its outputs in another +order, so a number can wire a FLOAT where an INT went. `comfy workflow slots +"/cloud.json"` prints each node's slot names. + **Asking about a lossy swap.** One message: each swap as `original -> replacement` and how the output may change; then two choices. **Swap**: runs on Comfy Cloud, nothing to build, output may differ. **Keep the original**: a custom build, with @@ -159,12 +178,12 @@ its costs. Offer only replacements from the same model family, taken from **Check every changed copy before running it.** Pack versions move widget values: ```shell -comfy --json run --workflow --print-prompt --where cloud > preview.json -jq '.data.prompt' preview.json > api.json -comfy --json workflow validate --workflow api.json --where cloud +comfy --json run --workflow "/cloud.json" --print-prompt --where cloud > "/preview.json" +jq '.data.prompt' "/preview.json" > "/api.json" +comfy --json workflow validate --workflow "/api.json" --where cloud ``` -Fix a widget by name with `comfy --json workflow set-widget +Fix a widget by name with `comfy --json workflow set-widget "/cloud.json" . --where cloud`, only to a value that keeps the saved behavior. @@ -234,7 +253,7 @@ Never call it working before a real job succeeds. `IMPORT FAILED` for a pack the workflow uses. Make the API file against the local server, which has the packs: `COMFY_LOCAL_URL= comfy --json run --workflow --print-prompt --where local`, - `.data.prompt` into `api.json`. + `.data.prompt` into `"/api.json"`. `deploy run` sends local files on its own. Any string input in `api.json` with a file extension can match a file, whatever the node type, so a custom @@ -244,7 +263,7 @@ Never call it working before a real job succeeds. which reuses files the deployment already has and sends none: ```shell - comfy --json deploy run --deployment --workflow api.json --no-upload \ + comfy --json deploy run --deployment --workflow "/api.json" --no-upload \ --wait --output-dir "/outputs" ``` @@ -258,7 +277,7 @@ Never call it working before a real job succeeds. by one `--allow-upload ` per approved file: ```shell - comfy --json deploy run --deployment --workflow api.json \ + comfy --json deploy run --deployment --workflow "/api.json" \ --allow-upload --allow-upload \ --wait --output-dir "/outputs" ``` diff --git a/tests/comfy_cli/skills/test_installer.py b/tests/comfy_cli/skills/test_installer.py index 5e473128a..2eaf1c6a4 100644 --- a/tests/comfy_cli/skills/test_installer.py +++ b/tests/comfy_cli/skills/test_installer.py @@ -1421,3 +1421,19 @@ def test_run_on_cloud_skill_fetches_files_with_any_name(): assert '--data-urlencode "subfolder="' in text assert "a space as `%20`" in text assert "run-on-cloud/" not in text + + +def test_run_on_cloud_skill_confirms_the_server_and_keeps_files_in_its_folder(): + """Another program on the prompt's port answers every path with 200, so the + skill confirms ComfyUI before fetching; a model with no local copy is asked + about only when the server has it; a swap wires slots by name; and every + file it writes stays under ``.""" + text = " ".join(skill_content("comfy-run-on-cloud").split()) + assert '"/api/system_stats"' in text + assert "`system.comfyui_version`" in text + assert '"/api/models/"' in text + assert "Name slots in `connect`, never their numbers" in text + assert '> "/preview.json"' in text + assert '--workflow "/api.json"' in text + assert "> preview.json" not in text + assert "--workflow api.json" not in text From 6f9083fb92ba22d18f15a15c517d4187383cc2f6 Mon Sep 17 00:00:00 2001 From: Vinh Trinh Date: Thu, 5 Nov 2026 05:49:53 -0500 Subject: [PATCH 6/7] docs(skills): single-quote names from the workflow, ask with the fetched input's hash, ask before partner-node spend - a file or workflow name inside double quotes still runs $(...); names from the workflow, server or disk now go in single quotes; - the input is fetched and hashed before the ask, and that same file is uploaded; - spend_consent_required is asked about, then the run repeats with --allow-spend. --- comfy_cli/skills/comfy-run-on-cloud/SKILL.md | 42 ++++++++++++++------ tests/comfy_cli/skills/test_installer.py | 19 ++++++++- 2 files changed, 46 insertions(+), 15 deletions(-) diff --git a/comfy_cli/skills/comfy-run-on-cloud/SKILL.md b/comfy_cli/skills/comfy-run-on-cloud/SKILL.md index c50876064..69ff3075b 100644 --- a/comfy_cli/skills/comfy-run-on-cloud/SKILL.md +++ b/comfy_cli/skills/comfy-run-on-cloud/SKILL.md @@ -24,6 +24,7 @@ Each of these needs its own yes in chat, asked before you do it: path, size, what it is for, where it goes. A yes covers the files you named; a new or changed file needs a new yes; - a **lossy** change (step 4); +- running **partner-API nodes**, which spend credits on top of the run (step 6); - a **new build or deployment** (it costs money to build and to keep running); - stopping, deleting or replacing any existing build, release or deployment. @@ -51,7 +52,10 @@ other character outside letters, digits, `-`, `_` and `.` the same way. Do all work in one folder, written `` below: `run-on-cloud/` plus the workflow's name with every character other than a letter, digit, `-` or `_` turned into `-` (`My flow (2)` gives `run-on-cloud/My-flow--2-`). Quote every -path in the commands. +path in the commands. Put each name that comes from the workflow, the server or +the disk (a file, subfolder, folder or workflow name) in single quotes, writing +a `'` inside it as `'\''`: inside double quotes the shell still runs `$(...)` +and backticks. First make sure the address is ComfyUI: `curl -sf "/api/system_stats"` must answer JSON with `system.comfyui_version`. Anything else (no answer, a web @@ -82,7 +86,7 @@ Pass each folder that exists as its own `--models-dir`: ```shell comfy --json which comfy --json workflow check "/original.json" --where cloud \ - --models-dir "" [--models-dir ""] + --models-dir '' [--models-dir ''] ``` Without `--models-dir` the check cannot see a local file, so a model the person @@ -115,7 +119,7 @@ folders: ```shell comfy --json workflow check "/original.json" --where cloud \ - --models-dir "" --apply-remaps --out "/cloud.json" + --models-dir '' --apply-remaps --out "/cloud.json" ``` Run `cloud.json` from here on. If any of its `models[]` rows is still @@ -149,7 +153,7 @@ at the first that works: to a custom build. 4. **A custom build.** Read `comfy skills show comfy-build` and `comfy skills show comfy-deploy`, and follow them. Build only what this workflow loads: - `comfy --json build init --name --from-workflow `. Before + `comfy --json build init --name '' --from-workflow "/cloud.json"`. Before building, show the plan and get a yes: what it uploads, the GPU and region (cheapest that fits first, from `comfy --json deploy refs compute`), the costs, and `--min 0 --max 1` workers. @@ -200,7 +204,7 @@ The dry run sends no file; it hashes the file here and reads the library: ```shell comfy --json model list-folders --where cloud -comfy --json model upload --type --workspace --where cloud --dry-run +comfy --json model upload '' --type --workspace --where cloud --dry-run ``` `` is the item's `folder` when `model list-folders` lists it; otherwise @@ -210,7 +214,7 @@ needs uploading or asking; use its `loader_path`. Otherwise ask by `filename`, with the dry run's path, `size`, `sha256` and destination folder. After the yes: ```shell -comfy --json model upload --type --workspace --where cloud \ +comfy --json model upload '' --type --workspace --where cloud \ --yes --expected-sha256 ``` @@ -230,13 +234,21 @@ in its place; report the model as what blocks the run. When it fails, nothing ra | `asset_upload_unverified` | The file is stored, but Cloud's hash of it does not match or could not be read. Do not run a workflow that loads it; report it, with `details.asset_id` | **An input file** (image, video, audio) a loader names: fetch it from the local -server, then upload it after the yes: +server before you ask, then ask with the fetched file's size and its +`shasum -a 256` hash: ```shell -curl -sfG "/api/view" --data-urlencode "filename=" \ - --data-urlencode "subfolder=" --data-urlencode "type=input" \ - -H "comfy-user: " -o "/inputs/" -comfy --json upload "/inputs/" --where cloud +curl -sfG "/api/view" --data-urlencode 'filename=' \ + --data-urlencode 'subfolder=' --data-urlencode "type=input" \ + -H "comfy-user: " -o '/inputs/' +shasum -a 256 '/inputs/' +``` + +After the yes, upload that same file. Do not fetch it again: if the server's +file has to be read again, ask again with the new hash. + +```shell +comfy --json upload '/inputs/' --where cloud ``` Set the loader on the copy to the returned `uploads[].cloud_name`. @@ -248,6 +260,10 @@ Never call it working before a real job succeeds. - **Comfy Cloud:** `comfy --json run --workflow --where cloud --wait`, then `comfy --json download --where cloud --out-dir "/outputs"`. + `spend_consent_required` means nothing was submitted: the workflow has + partner-API nodes (`details.partner_nodes`) that spend credits beyond the run. + Ask, naming those nodes; after a yes, run the same command with + `--allow-spend`. On a no, report "prepared, not run". - **A deployment** (existing or custom build): first read `comfy --json deploy logs --deployment `; `data.comfyuiLog` must show no `IMPORT FAILED` for a pack the workflow uses. Make the API file against the @@ -307,8 +323,8 @@ to recover a download. Run comfy commands one at a time. Save the file that ran (the copy, if you changed one): ```shell -comfy --json workflow save --name "" --where cloud -comfy --json workflow save --name "" --where cloud --deployment # ran on a deployment +comfy --json workflow save --name '' --where cloud +comfy --json workflow save --name '' --where cloud --deployment # ran on a deployment ``` It saves into a new folder in the Cloud Workflows sidebar and never replaces a diff --git a/tests/comfy_cli/skills/test_installer.py b/tests/comfy_cli/skills/test_installer.py index 2eaf1c6a4..59ad80e18 100644 --- a/tests/comfy_cli/skills/test_installer.py +++ b/tests/comfy_cli/skills/test_installer.py @@ -1417,8 +1417,11 @@ def test_run_on_cloud_skill_fetches_files_with_any_name(): name is made safe and created with its `inputs` folder, and paths are quoted.""" text = " ".join(skill_content("comfy-run-on-cloud").split()) assert 'mkdir -p "/inputs"' in text - assert '--data-urlencode "filename="' in text - assert '--data-urlencode "subfolder="' in text + assert "--data-urlencode 'filename='" in text + assert "--data-urlencode 'subfolder='" in text + assert "inside double quotes the shell still runs `$(...)`" in text + assert '"filename="' not in text + assert '--name ""' not in text assert "a space as `%20`" in text assert "run-on-cloud/" not in text @@ -1437,3 +1440,15 @@ def test_run_on_cloud_skill_confirms_the_server_and_keeps_files_in_its_folder(): assert '--workflow "/api.json"' in text assert "> preview.json" not in text assert "--workflow api.json" not in text + + +def test_run_on_cloud_skill_asks_about_the_exact_input_and_partner_spend(): + """The input is fetched and hashed before the ask, so the yes covers the + bytes that are uploaded; partner-API nodes spend credits beyond the run, so + `spend_consent_required` is asked about before `--allow-spend`.""" + text = " ".join(skill_content("comfy-run-on-cloud").split()) + assert "fetch it from the local server before you ask" in text + assert "shasum -a 256 '/inputs/'" in text + assert "Do not fetch it again" in text + assert "`spend_consent_required`" in text + assert "`--allow-spend`" in text From fede73ad2b224887709d71e65681a54c874d5834 Mon Sep 17 00:00:00 2001 From: Vinh Trinh Date: Thu, 5 Nov 2026 06:15:23 -0500 Subject: [PATCH 7/7] docs(skills): ask about models the server lookup cannot place, build from the file that exists, read output names from nodes show, keep input subfolders From the CodeRabbit pass on 6f9083f. --- comfy_cli/skills/comfy-run-on-cloud/SKILL.md | 22 +++++++++++++------- tests/comfy_cli/skills/test_installer.py | 6 +++++- 2 files changed, 20 insertions(+), 8 deletions(-) diff --git a/comfy_cli/skills/comfy-run-on-cloud/SKILL.md b/comfy_cli/skills/comfy-run-on-cloud/SKILL.md index 69ff3075b..394226dc9 100644 --- a/comfy_cli/skills/comfy-run-on-cloud/SKILL.md +++ b/comfy_cli/skills/comfy-run-on-cloud/SKILL.md @@ -97,7 +97,8 @@ file: `curl -sf "/api/models/"` lists the file names it loads from that folder. Listed there: the `--models-dir` folders are the wrong ones; ask the person where that server keeps its models and check again with that folder. Not listed: the file is not on this machine either, so there is nothing -to ask; go on with the verdict. +to ask; go on with the verdict. When the item's `folder` is null or the lookup +fails, the server's answer proves nothing: ask the person where the model is. `data.verdict` decides the next step: @@ -153,7 +154,9 @@ at the first that works: to a custom build. 4. **A custom build.** Read `comfy skills show comfy-build` and `comfy skills show comfy-deploy`, and follow them. Build only what this workflow loads: - `comfy --json build init --name '' --from-workflow "/cloud.json"`. Before + `comfy --json build init --name '' --from-workflow `, where + `` is `"/cloud.json"` when you made a copy and + `"/original.json"` otherwise. Before building, show the plan and get a yes: what it uploads, the GPU and region (cheapest that fits first, from `comfy --json deploy refs compute`), the costs, and `--min 0 --max 1` workers. @@ -170,8 +173,8 @@ at the first that works: each link, `workflow set-widget` for each value, and `workflow delete-nodes` for the nodes it replaces. Name slots in `connect`, never their numbers (`.INT`, not `.0`): the core node may list its outputs in another -order, so a number can wire a FLOAT where an INT went. `comfy workflow slots -"/cloud.json"` prints each node's slot names. +order, so a number can wire a FLOAT where an INT went. `comfy --json nodes show + --where cloud` lists a node's inputs and outputs by name. **Asking about a lossy swap.** One message: each swap as `original -> replacement` and how the output may change; then two choices. **Swap**: runs on Comfy Cloud, @@ -240,15 +243,20 @@ server before you ask, then ask with the fetched file's size and its ```shell curl -sfG "/api/view" --data-urlencode 'filename=' \ --data-urlencode 'subfolder=' --data-urlencode "type=input" \ - -H "comfy-user: " -o '/inputs/' -shasum -a 256 '/inputs/' + -H "comfy-user: " --create-dirs -o '/inputs//' +shasum -a 256 '/inputs//' ``` +Keep the subfolder in the path, so two inputs of the same name in different +subfolders stay two files. A subfolder or file name with `..` or a leading `/` +would write outside ``: do not fetch it; report that input as what blocks +the run. + After the yes, upload that same file. Do not fetch it again: if the server's file has to be read again, ask again with the new hash. ```shell -comfy --json upload '/inputs/' --where cloud +comfy --json upload '/inputs//' --where cloud ``` Set the loader on the copy to the returned `uploads[].cloud_name`. diff --git a/tests/comfy_cli/skills/test_installer.py b/tests/comfy_cli/skills/test_installer.py index 59ad80e18..a2f779463 100644 --- a/tests/comfy_cli/skills/test_installer.py +++ b/tests/comfy_cli/skills/test_installer.py @@ -1436,6 +1436,9 @@ def test_run_on_cloud_skill_confirms_the_server_and_keeps_files_in_its_folder(): assert "`system.comfyui_version`" in text assert '"/api/models/"' in text assert "Name slots in `connect`, never their numbers" in text + assert "lists a node's inputs and outputs by name" in text + assert "the server's answer proves nothing" in text + assert '`"/original.json"` otherwise' in text assert '> "/preview.json"' in text assert '--workflow "/api.json"' in text assert "> preview.json" not in text @@ -1448,7 +1451,8 @@ def test_run_on_cloud_skill_asks_about_the_exact_input_and_partner_spend(): `spend_consent_required` is asked about before `--allow-spend`.""" text = " ".join(skill_content("comfy-run-on-cloud").split()) assert "fetch it from the local server before you ask" in text - assert "shasum -a 256 '/inputs/'" in text + assert "shasum -a 256 '/inputs//'" in text + assert "--create-dirs -o '/inputs//'" in text assert "Do not fetch it again" in text assert "`spend_consent_required`" in text assert "`--allow-spend`" in text