# https://github.com/Comfy-Org/ComfyUI-Manager Project Manual

Generated at: 2026-06-15 00:19:33 UTC

## Table of Contents

- [Overview and Architecture](#page-overview)
- [Node and Model Management System](#page-node-management)
- [Configuration, Security, and Operations](#page-config-security-ops)
- [Component Sharing, CLI, and Advanced Tools](#page-sharing-cli-advanced)

<a id='page-overview'></a>

## Overview and Architecture

### Related Pages

Related topics: [Node and Model Management System](#page-node-management), [Configuration, Security, and Operations](#page-config-security-ops)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)
- [__init__.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/__init__.py)
- [glob/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/README.md)
- [js/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/README.md)
- [node_db/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/node_db/README.md)
- [prestartup_script.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/prestartup_script.py)
- [docs/en/v3.38-userdata-security-migration.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/v3.38-userdata-security-migration.md)
</details>

# Overview and Architecture

## 1. Purpose and Scope

**ComfyUI-Manager** is a third-party extension for [ComfyUI](https://github.com/comfyanonymous/ComfyUI) that augments the host application with lifecycle management for custom nodes, model downloading, workflow sharing, snapshot/restore, and a protected user-data path. It does not generate images itself; instead, it acts as a control plane that discovers, installs, updates, disables, and removes the Python and JavaScript node packs that ComfyUI loads at startup. Source: [README.md:1-7]().

The manager is delivered as a regular ComfyUI custom node and is installed under `ComfyUI/custom_nodes/ComfyUI-Manager/`. It registers hooks that let it integrate with the ComfyUI frontend and respond to server lifecycle events. Source: [README.md:55-58]()

The scope of the project includes:
- Discovery of community nodes via both an offline JSON catalog and the online **Custom Node Registry (CNR)** at `https://registry.comfy.org/`. Source: [README.md:11-12]()
- Installation of node packs from Git, pip, or the CNR channel.
- Model downloading with configurable base paths.
- Snapshot/restore of the installed node set.
- A multi-level security policy that gates risky operations.
- Workflow sharing to third-party platforms such as `comfyworkflows.com`, `openart.ai`, and `youml.com`. Source: [README.md:122-132]()

## 2. High-Level Architecture

The codebase is split into three cooperating tiers that communicate over ComfyUI's existing HTTP and WebSocket surface. The Python tier handles installation, git operations, security checks, and a REST API. The JavaScript tier renders the dialogs, tables, and menus that the user sees inside ComfyUI. A bundled node catalog and an online registry provide the metadata used to populate the UI. Source: [glob/README.md:7-12](), [js/README.md:7-21]().

```mermaid
flowchart LR
    User([User in ComfyUI UI])
    subgraph FE["JavaScript Frontend (js/)"]
        UI["comfyui-manager.js<br/>custom-nodes-manager.js<br/>model-manager.js"]
        API["cm-api.js"]
    end
    subgraph BE["Python Backend (glob/)"]
        Srv["manager_server.py<br/>REST endpoints"]
        Core["manager_core.py<br/>install / update / disable"]
        Dl["manager_downloader.py<br/>git + pip + http"]
        Sec["security_check.py<br/>policy levels"]
        Git["git_utils.py"]
        CNR["cnr_utils.py"]
    end
    subgraph DATA["Data Sources"]
        Local["node_db/*.json<br/>offline catalog"]
        Online["registry.comfy.org<br/>CNR online"]
        Cfg["config.ini<br/>channels.list<br/>pip_blacklist.list"]
    end
    ComfyUI[ComfyUI Host Process]
    User --> UI
    UI <--> API
    API -- "HTTP /manager/*" --> Srv
    Srv --> Core
    Core --> Dl
    Core --> Git
    Core --> CNR
    Core --> Sec
    Core --> Cfg
    Srv --> Local
    Srv --> Online
    Core --> ComfyUI
```

The frontend never accesses the filesystem directly. All privileged operations — cloning repos, running pip, writing to `custom_nodes/`, or editing config — are brokered by the backend through endpoints defined in `manager_server.py`. Source: [glob/README.md:13-17](), [js/README.md:11-15]().

## 3. Core Components

### 3.1 Backend (`glob/`)

The Python backend follows a modular layout with a clear separation between the orchestrator (`manager_core.py`), the transport layer (`manager_server.py`), and several specialized helpers. Source: [glob/README.md:7-12]().

| Module | Responsibility |
|---|---|
| `manager_core.py` | Central implementation of configuration, installation, updates, and node lifecycle. |
| `manager_server.py` | REST API endpoints exposed to the frontend. |
| `manager_downloader.py` | Download logic for models, extensions, and remote resources. |
| `git_utils.py` | Repository clone, fetch, reset, and ref operations. |
| `cnr_utils.py` | Helpers for the online Custom Node Registry. |
| `node_package.py` | Packaging of node extensions for installation. |
| `security_check.py` | Multi-level policy enforcement (see Section 4). |
| `share_3rdparty.py` | Integration with sharing platforms. |
| `cm_global.py` | Process-wide state and global variables. |
| `manager_util.py` | Shared utility helpers. |

Source: [glob/README.md:7-12]()

A pre-startup hook (`prestartup_script.py`) runs before ComfyUI finishes initializing, giving the manager a chance to restore pip versions, refresh channels, and prepare the user-data directory. Source: [prestartup_script.py:1-120]()

### 3.2 Frontend (`js/`)

The JavaScript layer is component-based. The entry point `comfyui-manager.js` injects itself into ComfyUI's existing app shell, while dedicated modules render the **Custom Nodes Manager**, **Model Manager**, **Components Manager**, and **Snapshot** dialogs. Sharing integrations (Copus, OpenArt, YouML) are isolated so a failure in one platform does not affect the others. Source: [js/README.md:7-15]().

The `workflow-metadata.js` module parses and validates workflow JSON, tracking version, dependencies, and resource references so the manager can offer "Install Missing Custom Nodes" actions. Source: [js/README.md:15-21]().

### 3.3 Node Catalog (`node_db/`)

The catalog is a directory of JSON files that describe known custom nodes, models, and extension-to-node class mappings. Subdirectories (`dev/`, `legacy/`, `new/`, `forked/`, `tutorial/`) segment entries by channel and lifecycle stage, while `scan.sh` regenerates the maps from Git. Source: [node_db/README.md:7-26]()

This local catalog is being progressively replaced by the online **CNR**; both are supported during the transition. Source: [node_db/README.md:31-40]()

## 4. Security and Configuration

Security is implemented as discrete policy levels that gate individual operations. The level is set in `config.ini` and consulted by `security_check.py` before any high-risk action. Source: [glob/README.md:21-29](), [README.md:241-256]().

| Level | Permits | Notable Restrictions |
|---|---|---|
| `strong` | Read-only browsing. | Blocks all `high` and `middle` level features. |
| `normal` (default) | Install from the default channel, uninstall, restore snapshots, restart. | Blocks `Install via git url`, `pip install`, and non-default channels. |
| `normal-` | Same as `normal` when not listening on a public interface. | Tightens when `--listen` exposes the server. |
| `weak` | Everything, including arbitrary git URLs and pip installs. | Reserved for development. |

A complementary set of files (`pip_blacklist.list`, `pip_overrides.json`, `pip_auto_fix.list`, `channels.list`) lets administrators further constrain what the manager is allowed to do. Source: [README.md:200-216]()

Starting with **V3.38**, all state files were moved to a protected `<USER_DIRECTORY>/__manager/` (or `default/ComfyUI-Manager/` on older ComfyUI) so they can no longer be overwritten by a malicious node that lands in `custom_nodes/`. Source: [docs/en/v3.38-userdata-security-migration.md:1-30](), [README.md:135-148]().

## 5. Known Operational Issues

Several recurring community issues map directly to the architecture above:

- **Silent install failures** (#2900) occur when the default `security_level` blocks the operation; the frontend reports success because the backend refuses the request without surfacing the reason. Source: [README.md:241-256]()
- **Missing menu after ComfyUI Desktop update** (#2374, #328) is caused by the JS bundle failing to load; users typically resolve it by re-cloning into `custom_nodes/ComfyUI-Manager`. Source: [README.md:42-50]()
- **"pip is required" warnings when using uv** (#1828) arise because the manager invokes the `pip` CLI from `security_check.py` even when the venv was created with `uv`; setting `use_uv = True` in `config.ini` (added in V3.16) addresses this. Source: [README.md:8-10]()
- **Stuck version indicator on v3.40 while v4 is in beta** (#2916) reflects the multi-branch release model; the user must explicitly switch to the v4 branch to receive the new series. Source: [README.md:1-12]()
- **Malicious node re-installing itself** (#2979) is mitigated by the V3.38 protected-path migration, but administrators are still expected to review new entries and report suspicious behavior.

## See Also

- [Node Database (node_db)](./node-database.md)
- [Configuration Reference](./configuration.md)
- [Security Policy and Risk Levels](./security.md)
- [Migration Guide: V3.38 Protected Path](./v3.38-userdata-security-migration.md)

---

<a id='page-node-management'></a>

## Node and Model Management System

### Related Pages

Related topics: [Overview and Architecture](#page-overview), [Configuration, Security, and Operations](#page-config-security-ops)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [glob/manager_core.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/manager_core.py)
- [glob/manager_server.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/manager_server.py)
- [glob/manager_downloader.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/manager_downloader.py)
- [glob/cnr_utils.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/cnr_utils.py)
- [glob/node_package.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/node_package.py)
- [glob/security_check.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/security_check.py)
- [js/custom-nodes-manager.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/custom-nodes-manager.js)
- [js/model-manager.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/model-manager.js)
- [js/cm-api.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/cm-api.js)
- [js/comfyui-manager.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/comfyui-manager.js)
- [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)
</details>

# Node and Model Management System

## Purpose and Scope

The Node and Model Management System is the central feature of ComfyUI-Manager, providing an integrated workflow for discovering, installing, updating, disabling, and removing custom nodes and AI models inside a running ComfyUI instance. It exposes both a backend REST surface (driven by Python modules under `glob/`) and a browser-side dialog UI (driven by modules under `js/`) so that users can manage their ComfyUI ecosystem without manually editing the filesystem.

The system targets three primary artifacts:

1. **Custom nodes** — Git repositories cloned under `ComfyUI/custom_nodes/`, optionally registered in the local `node_db/` database or the online Custom Node Registry (CNR) at `https://registry.comfy.org/`.
2. **Models** — Checkpoints, VAEs, LoRAs, ControlNets, and other weights downloaded into directories specified by `extra_model_paths.yaml`.
3. **Snapshots and components** — Saved installation states and reusable workflow fragments stored under the protected user directory introduced in V3.38 (`Source: [README.md]()`).

The system bridges three information sources: the legacy local JSON databases (`node_db/dev`, `node_db/new`, `node_db/legacy`, `node_db/forked`, `node_db/tutorial`), the live CNR, and the user's local filesystem (`Source: [node_db/README.md]()`).

## Architecture

The implementation follows a strict client/server separation. The backend in `glob/` is loaded into ComfyUI's Python process and registers API routes; the frontend in `js/` is loaded as a browser extension and calls those routes.

```mermaid
flowchart LR
    UI[ComfyUI Browser UI] -->|menu click| FD[comfyui-manager.js]
    FD -->|init| API[cm-api.js]
    FD -->|dialog| CN[custom-nodes-manager.js]
    FD -->|dialog| MM[model-manager.js]
    CN -->|HTTP GET/POST| SRV[manager_server.py]
    MM -->|HTTP GET/POST| SRV
    SRV --> CORE[manager_core.py]
    CORE --> DL[manager_downloader.py]
    CORE --> PKG[node_package.py]
    CORE --> SEC[security_check.py]
    CORE --> CNR[cnr_utils.py]
    DL --> FS[(ComfyUI filesystem)]
    PKG --> FS
    CNR --> REG[(registry.comfy.org)]
    SEC --> FS
    CORE --> DB[(node_db/*.json)]
```

`comfyui-manager.js` initializes the manager after ComfyUI's `app.js` finishes loading and registers the top-bar Manager button (`Source: [js/comfyui-manager.js]()`). `cm-api.js` is a thin client wrapper that issues fetch requests against the routes registered by `manager_server.py` (`Source: [js/cm-api.js]()`).

## Node Lifecycle

The node lifecycle is implemented in `manager_core.py` and exposed through `manager_server.py`. The typical operations are:

| Operation | Triggered by | Backend routine |
|-----------|-------------|-----------------|
| Install (git URL) | "Install via git URL" button | `install_custom_node` / git clone + `install.py` |
| Install (registry) | "Install" in node list | CNR fetch + `node_package.install` |
| Update | "Update" / "Update All" | `git pull` then re-run dependency install |
| Disable / Enable | Toggle in node list | Rename directory to `.disabled` suffix |
| Remove / Uninstall | "Remove" / "Uninstall" | `git`-based removal + `pip` uninstall |
| Snapshot save/restore | Snapshot Manager dialog | `save_snapshot` / `restore_snapshot` |

`Source: [glob/manager_core.py]()` and `Source: [glob/node_package.py]()` coordinate dependency installation, including the `pip_overrides.json`, `pip_blacklist.list`, and `pip_auto_fix.list` files documented in the README (`Source: [README.md]()`).

Security is enforced at every step by `security_check.py`, which classifies operations by risk tier (`block`, `high`, `middle`, `normal-`, `weak`) and blocks dangerous operations when the configured security level does not permit them (`Source: [glob/security_check.py]()`).

## Model Management

Model management is driven by `manager_downloader.py`, which resolves model identifiers to URLs and writes them into the directories configured in `extra_model_paths.yaml`. The `model-manager.js` dialog renders the catalog fetched from the registry and from `node_db/model-list.json`, then issues `cm-cli`-compatible API calls to start a download (`Source: [js/model-manager.js]()`).

Models can be installed from:

- The official registry (CNR or `model-list.json`)
- A direct Civitai or HuggingFace URL
- A user-supplied URL

The `download_model_base` key in `extra_model_paths.yaml` controls the default install location (`Source: [README.md]()`). Reverse-proxy endpoints can be configured with the `GITHUB_ENDPOINT` and `HF_ENDPOINT` environment variables for environments with restricted outbound access.

## Failure Modes and Community-Noted Issues

The community context surfaces several recurring failure modes the management system must handle:

1. **Silent install failures with default config** — When the security level is `block` or `high`, install operations can be rejected without surfacing a UI error. Users report having to lower the security level or open the bottom panel to see the underlying message (`Source: community issue #2900`). The fix is to set `security_level = normal` or `weak` in `config.ini` for development environments (`Source: [README.md]()`).
2. **Manager extension fails to load after ComfyUI update** — A browser-side `TypeError: Failed to fetch dynamically imported module` for `/extensions/ComfyUI-Manager/comfyui-manager.js` indicates the extension cache is stale. Restarting ComfyUI or clearing the browser cache typically resolves it (`Source: community issue #328 and #2374`).
3. **Missing pip when using `uv`** — When ComfyUI is provisioned via `uv` and `requirements.txt` is installed without `pip`, the security scan and snapshot restore phases can fail with "No pip" errors. Enabling `use_uv = True` in `config.ini` (introduced in V3.16) routes dependency installation through `uv pip` instead (`Source: community issue #1828; [README.md]()`).
4. **Malicious-looking node re-installs itself** — Users have reported nodes that re-enable after being disabled, or that reappear after uninstall. Because the system clones arbitrary Git repositories by default, the security-level mechanism is the primary mitigation; running with `security_level = block` or `high` and only enabling trusted channels is recommended (`Source: community issue #2979`).
5. **Channel indicator is red** — A red `Channel` indicator at the top of the node list signals the active channel is not the default channel, which affects both the node list and "Update All" behavior (`Source: [README.md]()`).

## Configuration Summary

The most relevant `config.ini` keys for node and model management are documented in the README and parsed by `manager_core.py`:

| Key | Purpose |
|-----|---------|
| `security_level` | One of `block`, `high`, `middle`, `normal-`, `weak` |
| `network_mode` | `public`, `private`, or `offline` |
| `use_uv` | Use `uv` instead of `pip` for dependency installation |
| `file_logging` | Persist manager logs to disk |
| `git_exe` | Override path to `git` executable on Windows |
| `always_lazy_install` | Force lazy dependency install on every restart |

Source: [README.md](). Configuration values are read at startup and cached for the lifetime of the ComfyUI process (`Source: [glob/manager_core.py]()`).

## See Also

- [Configuration and Security Levels](README.md)
- [Snapshot Manager and Restore Workflow](README.md)
- [Migration Guide for V3.38 Protected User Directory](docs/en/v3.38-userdata-security-migration.md)
- [cm-cli Command-Line Tools](docs/en/cm-cli.md)
- [Using aria2 as the Downloader](docs/en/use_aria2.md)

---

<a id='page-config-security-ops'></a>

## Configuration, Security, and Operations

### Related Pages

Related topics: [Overview and Architecture](#page-overview), [Node and Model Management System](#page-node-management)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)
- [glob/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/README.md)
- [node_db/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/node_db/README.md)
- [js/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/README.md)
- [glob/security_check.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/security_check.py)
- [glob/manager_core.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/manager_core.py)
- [glob/manager_server.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/manager_server.py)
- [glob/manager_downloader.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/manager_downloader.py)
- [glob/cm_global.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/cm_global.py)
- [js/snapshot.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/snapshot.js)
- [pip_overrides.json.template](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/pip_overrides.json.template)
</details>

# Configuration, Security, and Operations

## Overview

ComfyUI-Manager operates as a configurable extension layer above ComfyUI, exposing a multi-level security model, a file-based configuration system, and a set of operational primitives (snapshotting, pip overrides, component sharing, channel switching). This page documents how those primitives are wired together in the source, what user-facing knobs exist, and where the community has reported the most friction. Source: [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md).

The system separates cleanly into three layers: a **backend** (`glob/`) that owns configuration, risk evaluation, and installation logic; a **node database** (`node_db/`) that catalogues extensions and models; and a **frontend** (`js/`) that surfaces the dialogs. Each layer has its own README explaining its scope. Source: [glob/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/README.md), [node_db/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/node_db/README.md), [js/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/README.md).

## Configuration System

### File Locations

Since v3.38, the Manager moved its data to a protected system path. The path the runtime actually uses depends on the host ComfyUI version. Source: [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md).

| ComfyUI Version | Manager Path |
|-----------------|--------------|
| v0.3.76+ (with System User API) | `<USER_DIRECTORY>/__manager/` |
| Older versions | `<USER_DIRECTORY>/default/ComfyUI-Manager/` |

The `<USER_DIRECTORY>` defaults to `ComfyUI/user` and can be overridden with `--user-directory`. The same path holds `config.ini`, `channels.list`, `pip_overrides.json`, `pip_blacklist.list`, `pip_auto_fix.list`, `snapshots/`, `startup-scripts/`, and `components/`. Source: [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md).

### `config.ini` Options

The configuration file is loaded by the backend on startup and read by `manager_core.py` to gate risky operations. Recognised keys include `security_level`, `always_lazy_install`, `network_mode`, `file_logging`, `use_uv`, and proxy endpoints. Source: [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md).

| Option | Accepted Values | Purpose |
|--------|-----------------|---------|
| `security_level` | `strong` / `normal` / `normal-` / `weak` | Gates which operations the user can trigger |
| `network_mode` | `public` / `private` / `offline` | Selects how channels are resolved |
| `use_uv` | boolean | Switches the installer from `pip` to `uv` (added in v3.16) |
| `file_logging` | boolean | Writes backend log lines to disk (default on) |

The `network_mode = private` setting expects a `channel_url` pointing at a private node DB; both `private` and `offline` fall back to the on-disk cache when remote fetches fail. Source: [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md).

### Pip Behaviour Overrides

Pip behaviour is governed by three sidecar files in the user directory. `pip_overrides.json` (see [pip_overrides.json.template](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/pip_overrides.json.template)) forces specific versions for selected packages. `pip_blacklist.list` outright blocks installations of listed package names. `pip_auto_fix.list` is a `requirements.txt`-style file that re-pins versions at startup or whenever a custom node install causes a drift. `--index-url` is honoured in the auto-fix file. Source: [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md).

### Environment Variables

Three environment variables proxy or relocate the install. `COMFYUI_PATH` overrides the host ComfyUI location. `GITHUB_ENDPOINT` and `HF_ENDPOINT` rewrite outbound URLs to GitHub and Hugging Face respectively, enabling use behind regional mirrors such as `https://mirror.ghproxy.com/https://github.com`. Source: [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md).

## Security Model

### Risk Levels

The Manager exposes four preset tiers that gate which operations are reachable from the UI. The mapping documented in the README is:

- `block` — blocks most remote operations (highest tier)
- `high` — only narrowly trusted operations (git-URL installs, pip installs, non-default-channel installs, Fix custom nodes)
- `middle` — uninstall/update, default-channel installs, snapshot restore/remove, restart
- `normal-` — also enables `middle` level risky features
- `weak` — every feature is available (lowest tier)

Source: [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md), [glob/security_check.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/security_check.py).

### Backend Enforcement

`glob/security_check.py` implements the risk-classification logic referenced by the README. `glob/manager_core.py` reads `security_level` from `config.ini` and dispatches installation requests only when the current level permits them; operations the level forbids are surfaced back to the frontend so the user can lower the level explicitly. The default behaviour is conservative, which has been the root cause of several community-reported issues — see the *Known Pitfalls* section below. Source: [glob/security_check.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/security_check.py), [glob/manager_core.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/manager_core.py).

### Data Flow

```mermaid
flowchart LR
    UI[Frontend dialog] --> API[manager_server.py]
    API --> Core[manager_core.py]
    Core -->|reads| Config[config.ini]
    Core -->|asks| Sec[security_check.py]
    Sec -->|allow/deny| Core
    Core -->|when allowed| DL[manager_downloader.py]
    DL --> Install[Install / Update / Snapshot]
    Install --> FS[(custom_nodes / models)]
```

Source: [glob/manager_server.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/manager_server.py), [glob/manager_core.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/manager_core.py), [glob/manager_downloader.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/manager_downloader.py), [glob/security_check.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/security_check.py).

## Common Operations

### Installation and Channel Selection

The Manager ships three database modes selectable from the dialog: `DB: Channel (1day cache)`, `DB: Local`, and `DB: Channel (remote)`. The 1-day cache refreshes on miss or expiry; the remote mode bypasses cache. Channel choice affects not only browsing but also `Update All`, so users should be aware of the scope. Source: [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md).

### Snapshots

Pressing `Save snapshot` (or invoking `Update All`) writes the current installation state to `<USER_DIRECTORY>/.../snapshots/`. The frontend snapshot UI is implemented in [js/snapshot.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/snapshot.js). `Restore` re-applies that state — caveat: snapshot fidelity for non-Git-managed nodes is incomplete per the README. Source: [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md).

### Component Sharing

Reusable workflow components can be copied, pasted, and drag-dropped via `.pack` or `.json` files under `<USER_DIRECTORY>/.../components/`. Pinned metadata includes `version`, `datetime`, optional `packname`, and `category`. Source: [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md).

### Workflow Sharing

The Share button publishes workflows to `comfyworkflows.com`, `openart.ai`, `youml.com`, or the Matrix channel. Per-platform adapters live in [js/comfyui-share-copus.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/comfyui-share-copus.js), [js/comfyui-share-openart.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/comfyui-share-openart.js), and [js/comfyui-share-youml.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/comfyui-share-youml.js); the common envelope is in [js/comfyui-share-common.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/comfyui-share-common.js). Source: [js/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/README.md).

## Known Pitfalls (Community-Reported)

- **Installs silently failing** — Issue #2900 reports that the default `security_level` blocks real installs while the UI reports success. The workaround is to lower the level in `config.ini` and inspect the bottom panel for the actual reason. Source: [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md).
- **Malicious node re-install** — Issue #2979 describes a node that re-installs after uninstall. Because `security_check.py` evaluates risk per install, users on `weak` or `normal-` should treat recent registry additions with suspicion and pin known-good snapshots.
- **Menu missing after update** — Issue #328 / #2374 trace back to path errors (decompression producing `ComfyUI-Manager/ComfyUI-Manager/...` or `-main` directories). The README explicitly forbids these layouts because updates cannot self-locate. Source: [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md).
- **`pip` missing in `uv` venvs** — Issue #1828 shows that switching `use_uv = True` without installing `pip` breaks the security-scan subprocess. The README's `use_uv` block was added in v3.16 but does not bootstrap `pip`. Source: [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md).
- **RunPod install no-op** — Issue #2985 reports clicks succeeding without `custom_nodes/` directories appearing, suggesting a working-directory mismatch between `manager_core.py` and the volume mount — a configuration concern rather than a security one.

## See Also

- Frontend Components — [js/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/README.md)
- Backend Modules — [glob/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/README.md)
- Legacy Node Database — [node_db/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/node_db/README.md)
- v3.38 Migration Guide — [docs/en/v3.38-userdata-security-migration.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/v3.38-userdata-security-migration.md)

---

<a id='page-sharing-cli-advanced'></a>

## Component Sharing, CLI, and Advanced Tools

### Related Pages

Related topics: [Node and Model Management System](#page-node-management), [Configuration, Security, and Operations](#page-config-security-ops)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [cm-cli.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/cm-cli.py)
- [cm-cli.sh](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/cm-cli.sh)
- [docs/en/cm-cli.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/cm-cli.md)
- [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)
- [js/comfyui-manager.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/comfyui-manager.js)
- [js/comfyui-share-common.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/comfyui-share-common.js)
- [js/comfyui-share-copus.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/comfyui-share-copus.js)
- [js/comfyui-share-openart.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/comfyui-share-openart.js)
- [js/comfyui-share-youml.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/comfyui-share-youml.js)
- [js/snapshot.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/snapshot.js)
- [js/workflow-metadata.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/workflow-metadata.js)
</details>

# Component Sharing, CLI, and Advanced Tools

This page documents the auxiliary capabilities of ComfyUI-Manager that sit alongside the primary install / update flow: workflow component sharing, the `cm-cli` command-line interface, and advanced configuration tools such as snapshot management and security profiles. These features are documented in the project README and exposed both in the in-app dialogs and via standalone scripts.

## Component Sharing

The Manager extends ComfyUI with a reusable-component system so that groups of nodes (subgraphs) can be packaged, exported, shared, and re-imported across workflows and users.

### Pack Format and Storage

Components are stored under `<USER_DIRECTORY>/default/ComfyUI-Manager/components/` and are persisted as either individual `components.json` entries or as pack files (`<packname>.pack`). A single component entry embeds the same node graph that would be produced when a user saves a group node, plus a small set of metadata fields: `version`, `datetime`, `packname`, and `category` (`Source: [README.md]() `). Only `major.minor.patch` or `major.minor` version forms are accepted; an invalid version causes the entry to be rejected on import.

### Copy / Paste and Drag & Drop

Two interactive pathways are supported:

- **Copy & Paste**: When a component JSON object is on the clipboard with `kind: "ComfyUI Components"` and a unique `timestamp`, the frontend parses it and re-injects the nodes. `Source: [js/comfyui-manager.js]() ` defines the paste handler that intercepts clipboard events of this `text/plain` shape.
- **Drag & Drop**: A user can drag a `.pack` or `.json` file onto the ComfyUI canvas. The frontend dispatches this to the same importer. `Source: [js/workflow-metadata.js]() ` contains the validator that checks the JSON envelope before reconstruction.

When multiple components are pasted at once, they are imported as nodes but not auto-added to the workflow; only a single dropped component triggers auto-insertion. The metadata inside the paste payload uses the `<prefix>::<node name>` naming convention so that collisions are detected.

### External Sharing Platforms

Beyond local clipboard sharing, the Manager integrates with three third-party hosting services through a common bridge: `Source: [js/comfyui-share-common.js]() `. Each integration is implemented as a thin module that adapts the common payload to the platform's API.

| Platform | Module | Notes |
|----------|--------|-------|
| ComfyWorkflows | `comfyui-share-copus.js` | Default; share via `https://comfyworkflows.com/`. `Source: [js/comfyui-share-copus.js]()` |
| OpenArt | `comfyui-share-openart.js` | Posts to `https://openart.ai/workflows/dev`. `Source: [js/comfyui-share-openart.js]()` |
| YouML | `comfyui-share-youml.js` | Posts to `https://youml.com`. `Source: [js/comfyui-share-youml.js]()` |

The Share button can be hidden (`None` setting) or replaced by a title-prompt dialog (`All` setting) via the Manager's Share settings. `Source: [README.md]() `

## cm-cli: Command-Line Interface

`cm-cli` is the official command-line entry point for users who do not want to operate the Manager from inside ComfyUI's GUI. The project ships both a Python launcher and a POSIX wrapper.

### Invocation

The Python entry point `cm-cli.py` and the shell wrapper `cm-cli.sh` both live at the repository root. On POSIX systems the wrapper is intended to be put on `PATH`; on Windows, `cm-cli.py` is invoked directly with Python. `Source: [cm-cli.py]()` and `Source: [cm-cli.sh]() `. The full command reference is maintained in `Source: [docs/en/cm-cli.md]()` .

### Common Tasks

`cm-cli` mirrors the operations exposed by the in-app Manager dialogs — install / remove / enable / disable custom nodes, list installed nodes, save and restore snapshots, switch channels, and toggle security levels. This is the recommended path for headless or remote setups where the GUI is not reachable, and it is mentioned in the README as part of the installation options. `Source: [README.md]() `

### Related CLI Tool: `comfy-cli`

For installing ComfyUI itself together with the Manager in one step, the README recommends `comfy-cli` (https://github.com/Comfy-Org/comfy-cli). `Source: [README.md]() ` This is a sibling project; `cm-cli` operates on an already-running Manager instance.

## Advanced Tools

### Snapshot Manager

The Snapshot Manager captures the full set of installed custom nodes and their versions so the environment can be rolled back to a known-good state. Snapshots are stored in `<USER_DIRECTORY>/default/ComfyUI-Manager/snapshots/` and can be renamed. The frontend logic lives in `Source: [js/snapshot.js]() `.

A snapshot is created automatically when `Update All` runs from the Manager menu or when `Save snapshot` is pressed. The Restore action re-applies the recorded versions, but with one documented limitation: custom nodes not installed via Git do not round-trip cleanly through the snapshot system. `Source: [README.md]() `

### Security Levels

The Manager gates risky operations behind a five-level security model configured in `config.ini`:

| Level | Permitted Risky Operations |
|-------|---------------------------|
| `block` | Only low-risk operations (e.g. UI browsing) |
| `high` | Git-URL installs, pip installs, fixing nodes, non-default channel installs |
| `middle` | Uninstall / update, default-channel installs, restore/remove snapshot, restart |
| `normal-` | Default level: includes `middle` operations |
| `weak` | All features available (development environments) |

`Source: [README.md]() ` and `Source: [glob/README.md]() `. If the default level silently blocks an install, users typically need to lower the level or adjust `network_mode` before re-attempting; this is a recurring friction point in community reports where installs appear to succeed in the UI but fail under the hood.

### Configuration Files

All configuration lives under the protected user directory that V3.38 introduced: `Source: [README.md]() `

| File | Purpose |
|------|---------|
| `config.ini` | Core settings (security level, network mode, file logging, `use_uv`) |
| `channels.list` | Curated channel sources |
| `pip_overrides.json` | Force specific pip package versions |
| `pip_blacklist.list` | Block pip packages |
| `pip_auto_fix.list` | Auto-restore pip versions on startup |
| `snapshots/` | Snapshot JSON files |
| `startup-scripts/` | Hooks executed on launch |
| `components/` | Saved reusable components |

Environment variables (`COMFYUI_PATH`, `GITHUB_ENDPOINT`, `HF_ENDPOINT`) override or proxy external hosts when access is restricted.

## See Also

- [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md) — full feature reference
- [docs/en/cm-cli.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/cm-cli.md) — `cm-cli` command reference
- [docs/en/v3.38-userdata-security-migration.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/v3.38-userdata-security-migration.md) — user-data path migration guide
- [docs/en/use_aria2.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/use_aria2.md) — configuring `aria2` as the downloader

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: Comfy-Org/ComfyUI-Manager

Summary: Found 12 structured pitfall item(s), including 4 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Comfy-Org/ComfyUI-Manager/issues/2916

## 2. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Comfy-Org/ComfyUI-Manager/issues/2900

## 3. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Comfy-Org/ComfyUI-Manager/issues/2969

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Comfy-Org/ComfyUI-Manager/issues/2985

## 5. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Comfy-Org/ComfyUI-Manager/issues/2979

## 6. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | github_repo:631600154 | https://github.com/Comfy-Org/ComfyUI-Manager

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | github_repo:631600154 | https://github.com/Comfy-Org/ComfyUI-Manager

## 8. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | github_repo:631600154 | https://github.com/Comfy-Org/ComfyUI-Manager

## 9. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | github_repo:631600154 | https://github.com/Comfy-Org/ComfyUI-Manager

## 10. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Comfy-Org/ComfyUI-Manager/issues/2951

## 11. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | github_repo:631600154 | https://github.com/Comfy-Org/ComfyUI-Manager

## 12. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | github_repo:631600154 | https://github.com/Comfy-Org/ComfyUI-Manager

<!-- canonical_name: Comfy-Org/ComfyUI-Manager; human_manual_source: deepwiki_human_wiki -->