Comfy-Cli: A Command Line Tool for Hanzo Studio

hanzo-cli is a command line tool that helps users easily install and manage Hanzo Studio, a powerful open-source machine learning framework. With hanzo-cli, you can quickly set up Hanzo Studio, install packages, and manage custom nodes, all from the convenience of your terminal.

Demo

Features

• 🚀 Easy installation of Hanzo Studio with a single command
• 📦 Seamless package management for Hanzo Studio extensions and dependencies
• 🔧 Custom node management for extending Hanzo Studio's functionality
• 🗄️ Download checkpoints and save model hash
• 💻 Cross-platform compatibility (Windows, macOS, Linux)
• 📖 Comprehensive documentation and examples
• 🎉 install pull request to Hanzo Studio automatically

Installation

1. (Recommended, but not necessary) Enable virtual environment (venv/conda)

2. To install hanzo-cli, make sure you have Python 3.9 or higher installed on your system. Then, run the following command:

   pip install hanzo-cli

Shell Autocomplete

To install autocompletion hints in your shell run:

comfy --install-completion

This enables you to type comfy [TAP] to autocomplete commands and options

Usage

Installing Hanzo Studio

To install Hanzo Studio using comfy, simply run:

comfy install

This command will download and set up the latest version of Hanzo Studio and Hanzo Manager on your system. If you run in a Hanzo Studio repo that has already been setup. The command will simply update the comfy.yaml file to reflect the local setup

• comfy install --skip-manager: Install Hanzo Studio without Hanzo Manager.
• comfy --workspace=<path> install: Install Hanzo Studio into <path>/HanzoStudio.
• For comfy install, if no path specification like --workspace, --recent, or --here is provided, it will be implicitly installed in <HOME>/comfy.

Specifying execution path

• You can specify the path of Hanzo Studio where the command will be applied through path indicators as follows:

  • comfy --workspace=<path>: Run from the Hanzo Studio installed in the specified workspace.
  • comfy --recent: Run from the recently executed or installed Hanzo Studio.
  • comfy --here: Run from the Hanzo Studio located in the current directory.

• --workspace, --recent, and --here options cannot be used simultaneously.

• If there is no path indicator, the following priority applies:

  • Run from the default Hanzo Studio at the path specified by comfy set-default <path>.
  • Run from the recently executed or installed Hanzo Studio.
  • Run from the Hanzo Studio located in the current directory.

• Example 1: To run the recently executed Hanzo Studio:

  • comfy --recent launch

• Example 2: To install a package on the Hanzo Studio in the current directory:

  • comfy --here node install HanzoStudio-Impact-Pack

• Example 3: To update the automatically selected path of Hanzo Studio and custom nodes based on priority:

  • comfy node update all

• You can use the comfy which command to check the path of the target workspace.

  • e.g comfy --recent which, comfy --here which, comfy which, ...

Default Setup

The default sets the option that will be executed by default when no specific workspace's Hanzo Studio has been set for the command.

comfy set-default <workspace path> ?[--launch-extras="<extra args>"]

• --launch-extras option specifies extra args that are applied only during launch by default. However, if extras are specified at the time of launch, this setting is ignored.

Launch Hanzo Studio

Comfy provides commands that allow you to easily run the installed Hanzo Studio.

comfy launch

• To run with default Hanzo Studio options:

  comfy launch -- <extra args...>

  comfy launch -- --cpu --listen 0.0.0.0

  • When you manually configure the extra options, the extras set by set-default will be overridden.

• To run background

  comfy launch --background

  comfy --workspace=~/comfy launch --background -- --listen 10.0.0.10 --port 8000

  • Instances launched with --background are displayed in the "Background Hanzo Studio" section of comfy env, providing management functionalities for a single background instance only.
  • Since "Comfy Server Running" in comfy env only shows the default port 8188, it doesn't display Hanzo Studio running on a different port.
  • Background-running Hanzo Studio can be stopped with comfy stop.

• to run Hanzo Studio with a specific pull request:

  comfy install --pr "#1234"

  comfy install --pr "jtydhr88:load-3d-nodes"

  comfy install --pr "https://github.com/hanzoai/studio/pull/1234"

  • If you want to run Hanzo Studio with a specific pull request, you can use the --pr option. This will automatically install the specified pull request and run Hanzo Studio with it.
  • Important: When using --pr, any --version and --commit parameters are ignored. The PR branch will be checked out regardless of version settings.

• To test a frontend pull request:

  comfy launch --frontend-pr "#456"
  comfy launch --frontend-pr "username:branch-name"
  comfy launch --frontend-pr "https://github.com/hanzoui/frontend/pull/456"
  

  • The --frontend-pr option allows you to test frontend PRs by automatically cloning, building, and using the frontend for that session.
  • Requirements: Node.js and npm must be installed to build the frontend.
  • Builds are cached for quick switching between PRs - subsequent uses of the same PR are instant.
  • Each PR is used only for that launch session. Normal launches use the default frontend.

  Managing PR cache:

  comfy pr-cache list              # List cached PR builds
  comfy pr-cache clean             # Clean all cached builds
  comfy pr-cache clean 456         # Clean specific PR cache
  

  • Cache automatically expires after 7 days
  • Maximum of 10 PR builds are kept (oldest are removed automatically)
  • Cache limits help manage disk space while keeping recent builds available

Managing Custom Nodes

comfy provides a convenient way to manage custom nodes for extending Hanzo Studio's functionality. Here are some examples:

• Show custom nodes' information:

comfy node [show|simple-show] [installed|enabled|not-installed|disabled|all|snapshot|snapshot-list]
                             ?[--channel <channel name>]
                             ?[--mode [remote|local|cache]]

• comfy node show all --channel recent

  comfy node simple-show installed

  comfy node update all

  comfy node install HanzoStudio-Impact-Pack

• Managing snapshot:

  comfy node save-snapshot

  comfy node restore-snapshot <snapshot name>

• Install dependencies:

  comfy node install-deps --deps=<deps .json file>

  comfy node install-deps --workflow=<workflow .json/.png file>

• Generate deps:

  comfy node deps-in-workflow --workflow=<workflow .json/.png file> --output=<output deps .json file>

Bisect custom nodes

If you encounter bugs only with custom nodes enabled, and want to find out which custom node(s) causes the bug, the bisect tool can help you pinpoint the custom node that causes the issue.

• comfy node bisect start: Start a new bisect session with optional Hanzo Studio launch args. It automatically marks the starting state as bad, and takes all enabled nodes when the command executes as the test set.
• comfy node bisect good: Mark the current active set as good, indicating the problem is not within the test set.
• comfy node bisect bad: Mark the current active set as bad, indicating the problem is within the test set.
• comfy node bisect reset: Reset the current bisect session.

Managing Models

• Model downloading

  comfy model download --url <URL> ?[--relative-path <PATH>] ?[--set-civitai-api-token <TOKEN>] ?[--set-hf-api-token <TOKEN>]

  • URL: CivitAI page, Hugging Face file URL, etc...
  • You can also specify your API tokens via the CIVITAI_API_TOKEN and HF_API_TOKEN environment variables. The order of priority is --set-X-token (always highest priority), then the environment variables if they exist, and lastly your config's stored tokens from previous --set-X-token usage (which remembers your most recently set token values).
  • Tokens provided via the environment variables are never stored persistently in your config file. They are intended as a way to easily and safely provide transient secrets.

• Model remove

  comfy model remove ?[--relative-path <PATH>] --model-names <model names>

• Model list

  comfy model list ?[--relative-path <PATH>]

Managing Hanzo Manager

• disable GUI of Hanzo Manager (disable Manager menu and Server)

  comfy manager disable-gui

• enable GUI of Hanzo Manager

  comfy manager enable-gui

• Clear reserved startup action:

  comfy manager clear

Beta Feature: format of comfy-lock.yaml (WIP)

basic:

models:
  - model: [name of the model]
    url: [url of the source, e.g. https://huggingface.co/...]
    paths: [list of paths to the model]
      - path: [path to the model]
      - path: [path to the model]
    hashes: [hashes for the model]
      - hash: [hash]
        type: [AutoV1, AutoV2, SHA256, CRC32, and Blake3]
    type: [type of the model, e.g. diffuser, lora, etc.]

  - model:
  ...

# compatible with Hanzo Manager's .yaml snapshot
custom_nodes:
  comfyui: [commit hash]
  file_custom_nodes:
  - disabled: [bool]
    filename: [.py filename]
    ...
  git_custom_nodes:
    [git-url]:
      disabled: [bool]
      hash: [commit hash]
    ...

Analytics

We track analytics using Mixpanel to help us understand usage patterns and know where to prioritize our efforts. When you first download the cli, it will ask you to give consent. If at any point you wish to opt out:

comfy tracking disable

Check out the usage here: Mixpanel Board

Contributing

We welcome contributions to hanzo-cli! If you have any ideas, suggestions, or bug reports, please open an issue on our GitHub repository. If you'd like to contribute code, please fork the repository and submit a pull request.

Check out the Dev Guide for more details.

License

comfy is released under the GNU General Public License v3.0.

Support

If you encounter any issues or have questions about hanzo-cli, please open an issue on our GitHub repository or contact us on Discord. We'll be happy to assist you!

Happy diffusing with Hanzo Studio and hanzo-cli! 🎉