> ## Documentation Index
> Fetch the complete documentation index at: https://comfyui-mcp.artokun.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# comfy-cli

> Drive the official comfy-cli — managed server lifecycle, jobs, loaded-node search, workflow validation/execution, uploads/downloads, model discovery, and official agent skills.

<Info>1 tool. Generated from the live MCP tool schemas — do not edit by hand; run `npm run docs:gen`.</Info>

<Tip>**You don't type these calls.** Ask your agent for what you want in ordinary English — it chooses the tool and fills in the arguments. The JSON on this page is what it sends. New here? Start with [Using the tools](/docs/using-tools).</Tip>

## comfy\_cli

Drive the official comfy-cli (envelope/1 JSON contract) for the selected ComfyUI environment. The MCP resolves `comfy` from COMFY\_CLI\_PATH, PATH, or the selected workspace's .venv/venv. Driven by the `action` parameter:

* action:"status" — Inspect the comfy-cli integration and selected environment (`comfy which` / `comfy env`); `detail` selects version/which/env/discover (default env). Call this before local CLI operations when workspace or server routing is uncertain.
* action:"server\_start" / "server\_stop" / "server\_restart" — Manage a local ComfyUI through comfy-cli background process management. Restart performs `comfy stop` followed by `comfy launch --background`; extra launch arguments go in `launchArgs`.
* action:"jobs\_list" — List local or Comfy Cloud jobs (`limit` optional). Local jobs include CLI-tracked async submissions plus the ComfyUI queue/history.
* action:"jobs\_status" / "jobs\_watch" / "jobs\_cancel" — Inspect, watch, or cancel one job; `promptId` required.
* action:"jobs\_wait" — Wait for jobs: one of `promptId`, `promptIds`, or all=true is required; `timeoutSeconds` optional.
* action:"search\_nodes" — Fuzzy-search actual ComfyUI node classes by name, display name, or description using `comfy nodes search`; `query` required. Complements search\_custom\_nodes, which searches installable node packs. Works locally, in Comfy Cloud, or offline with `objectInfoPath`. When comfy-cli is not installed/on PATH and the target is the connected (local) server, falls back to fuzzy-searching that server's live /object\_info — so installed-node discovery works without the CLI.
* action:"workflow\_validate" — Validate an API/UI workflow file (class types, inputs, enums, edge wiring) without submission; `workflowPath` required.
* action:"workflow\_run" — Submit an API/UI workflow file (`workflowPath` required). Asynchronous by default; set wait=true to await outputs (`timeoutSeconds`).
* action:"transfer\_upload" — Upload input files (`files` required) for local ComfyUI or Comfy Cloud; overwrite=false passes --no-overwrite.
* action:"transfer\_download" — Download completed outputs for `promptId` (required); `outDir` and `urlOnly` optional.
* action:"models\_list\_folders" / "models\_list\_folder" / "models\_search" / "models\_show" — Discover model folders/files locally or in Comfy Cloud (`folder` required for list\_folder, `name` for show). When comfy-cli is not installed/on PATH and the target is the connected (local) server, these read-only listings fall back to that server's own local models (via /models) — so model discovery works without the CLI.
* action:"models\_download" — Download a model `url` (required) into the workspace (`relativePath`, default models/checkpoints). A download can run for many minutes and is gated on an idle-liveness timeout, so a progressing download is never killed.
* action:"models\_remove" — Remove workspace model files (`modelNames` required; `relativePath` optional).
* action:"skills\_list" / "skills\_show" / "skills\_validate" / "skills\_install" / "skills\_status" / "skills\_uninstall" — Manage the official comfy-cli bundled agent skills (comfy, fragments, debug, relay, director). validate requires `path`; install/uninstall default to dry-run unless apply=true; scope="project" requires `projectDir`.

### Parameters

<ParamField path="action" type="enum" required>
  Which comfy-cli operation to perform. Families: status; server\_\* (lifecycle); jobs\_\* (list/status/wait/watch/cancel); search\_nodes; workflow\_\* (validate/run); transfer\_\* (upload/download); models\_\* (list\_folders/list\_folder/search/show/download/remove); skills\_\* (list/show/validate/install/status/uninstall). Options: `action:"status"`, `action:"server_start"`, `action:"server_stop"`, `action:"server_restart"`, `action:"jobs_list"`, `action:"jobs_status"`, `action:"jobs_wait"`, `action:"jobs_watch"`, `action:"jobs_cancel"`, `action:"search_nodes"`, `action:"workflow_validate"`, `action:"workflow_run"`, `action:"transfer_upload"`, `action:"transfer_download"`, `action:"models_list_folders"`, `action:"models_list_folder"`, `action:"models_search"`, `action:"models_show"`, `action:"models_download"`, `action:"models_remove"`, `action:"skills_list"`, `action:"skills_show"`, `action:"skills_validate"`, `action:"skills_install"`, `action:"skills_status"`, `action:"skills_uninstall"`.
</ParamField>

<ParamField path="detail" type="enum" default="env">
  action:"status" — which inspection to run. Options: `version`, `which`, `env`, `discover`.
</ParamField>

<ParamField path="workspace" type="string">
  Optional ComfyUI workspace override. Otherwise COMFYUI\_PATH/auto-detection is used.
</ParamField>

<ParamField path="launchArgs" type="string[]">
  actions "server\_start"/"server\_restart" — extra ComfyUI launch arguments, e.g. \['--listen','0.0.0.0','--port','8188'].
</ParamField>

<ParamField path="promptId" type="string">
  Single prompt id. Required for "jobs\_status"/"jobs\_watch"/"jobs\_cancel" and "transfer\_download"; accepted for "jobs\_wait" (normalized into a one-element promptIds list).
</ParamField>

<ParamField path="promptIds" type="string[]">
  action:"jobs\_wait" — prompt ids to wait on. Use this or promptId or all=true.
</ParamField>

<ParamField path="all" type="boolean">
  action:"jobs\_wait" — wait on every known job.
</ParamField>

<ParamField path="limit" type="integer">
  Result cap for "jobs\_list", "search\_nodes" and the "models\_\*" listing/search actions.
</ParamField>

<ParamField path="timeoutSeconds" type="integer">
  actions "jobs\_wait"/"jobs\_watch"/"workflow\_run" — max seconds to wait.
</ParamField>

<ParamField path="where" type="enum">
  Target for the jobs/search\_nodes/workflow/transfer/models actions: "local" (default) or "cloud" (Comfy Cloud). Options: `local`, `cloud`.
</ParamField>

<ParamField path="query" type="string">
  action:"search\_nodes" — fuzzy search text. REQUIRED.
</ParamField>

<ParamField path="objectInfoPath" type="string">
  action:"search\_nodes" — offline object\_info JSON file to search instead of a live target.
</ParamField>

<ParamField path="workflowPath" type="string">
  actions "workflow\_validate"/"workflow\_run" — path to an API/UI workflow JSON file. REQUIRED.
</ParamField>

<ParamField path="wait" type="boolean">
  action:"workflow\_run" — await outputs instead of returning after submission.
</ParamField>

<ParamField path="files" type="string[]">
  action:"transfer\_upload" — input files to upload. REQUIRED.
</ParamField>

<ParamField path="outDir" type="string">
  action:"transfer\_download" — output directory.
</ParamField>

<ParamField path="overwrite" type="boolean">
  action:"transfer\_upload" — set false to pass --no-overwrite.
</ParamField>

<ParamField path="urlOnly" type="boolean">
  action:"transfer\_download" — print URLs instead of downloading files.
</ParamField>

<ParamField path="folder" type="string">
  action:"models\_list\_folder" — the model folder to list. REQUIRED.
</ParamField>

<ParamField path="text" type="string">
  action:"models\_search" — search text.
</ParamField>

<ParamField path="type" type="string">
  action:"models\_search" — model type filter (checkpoint, lora, vae, …).
</ParamField>

<ParamField path="name" type="string">
  actions "models\_show"/"skills\_show" — the model or skill name.
</ParamField>

<ParamField path="url" type="string">
  action:"models\_download" — model URL to download. REQUIRED.
</ParamField>

<ParamField path="relativePath" type="string">
  actions "models\_download"/"models\_remove" — workspace-relative model directory (default models/checkpoints).
</ParamField>

<ParamField path="modelNames" type="string[]">
  action:"models\_remove" — model filenames to remove. REQUIRED.
</ParamField>

<ParamField path="path" type="string">
  action:"skills\_validate" — path to the skill to validate. REQUIRED.
</ParamField>

<ParamField path="scope" type="enum">
  actions "skills\_install"/"skills\_uninstall"/"skills\_status" — install scope. Options: `user`, `project`.
</ParamField>

<ParamField path="projectDir" type="string">
  Working directory for project-scoped skill operations. Required when scope='project'.
</ParamField>

<ParamField path="targets" type="string[]">
  actions "skills\_install"/"skills\_uninstall" — agent targets.
</ParamField>

<ParamField path="skills" type="string[]">
  actions "skills\_install"/"skills\_uninstall" — skill names.
</ParamField>

<ParamField path="apply" type="boolean" default="false">
  actions "skills\_install"/"skills\_uninstall" — actually mutate; default false = dry-run.
</ParamField>

### Example

<Note>No worked example yet — the call below is a skeleton generated from the required parameters. Real examples live in `scripts/tool-doc-examples.ts`; contributions welcome.</Note>

```json theme={null}
{
  "tool": "comfy_cli",
  "arguments": {
    "action": "status"
  }
}
```

***