kulai 0.2.2

AI asset and workflow package manager — resolve and download model dependencies for ComfyUI and other AI software

kulai

AI asset and workflow package manager — download, track, and share model dependencies for ComfyUI, A1111, Forge, InvokeAI, SwarmUI, and more.

---

What it does

Model workflows reference assets by filename only — no URLs, no sources, no way for someone else to reproduce your setup. kulai fixes that.

• Resolve a workflow and auto-find every model on HuggingFace and Civitai
• Install a .kula file to reproduce someone else's exact setup in one command
• Wizard to build a .kula file interactively — paste a Civitai or HuggingFace URL and it fills in filename, SHA256, VRAM hint, and type automatically
• Check which assets from a workflow are already present locally (no downloads, no API calls)
• Generate a .kula file from an existing workflow automatically

---

Installation

pip install kulai

Or with pipx (recommended — keeps it isolated):

pipx install kulai
pipx ensurepath

Requires Python 3.10+

---

.kula files

A .kula file is a portable manifest that lists every model a workflow needs, where to get it, and its SHA256 hash for verification. Share it alongside your workflow and anyone can reproduce your setup with one command.

[meta]
name    = "My Workflow"
author  = "you"
version = "1.0"

[[resource]]
display_name = "WAI Realism"
type         = "checkpoints"
required     = true
vram_gb      = 6.9
file_name    = "waiREALISM_v10.safetensors"
sha256       = "1E6EB29C..."
destination  = "models/checkpoints"

[resource.sources]
civitai = "https://civitai.com/api/download/models/2514670"

[[resource]]
display_name = "Some LoRA"
type         = "loras"
required     = false
file_name    = "my_lora.safetensors"

[resource.sources]
huggingface = "https://huggingface.co/someone/repo/resolve/main/my_lora.safetensors"

---

Quick start

Install a workflow's dependencies

kulai install my_workflow.kula

Build a .kula file interactively

kulai wizard

Paste any Civitai or HuggingFace URL and kulai fills in everything it can — filename, SHA256, VRAM, asset type — ready for you to review and confirm.

Generate a .kula from an existing workflow

kulai generate my_workflow.json

Check what's already installed

kulai check my_workflow.json

Resolve and download a workflow (no .kula file needed)

kulai resolve my_workflow.json

---

Commands

install

kulai install KULA_FILE [OPTIONS]

Option	Description
--required-only	Skip optional resources and custom nodes
--nodes-only	Clone custom nodes only, skip model downloads
--variant NAME	Override default variant for all resources (e.g. fp16, q8)
--download-dir PATH	Override destination for all resources
--concurrent N	Parallel downloads (1–16)
--yes / -y	Skip confirmation prompt
--no-civitai-info	Skip saving .civitai.info metadata sidecars

wizard

kulai wizard [--output FILE]

Interactive step-by-step builder. Works for any AI software — not ComfyUI-specific.

• Paste a Civitai URL (civitai.com or civitai.red) and it fetches filename, SHA256, size, and asset type from the API
• Paste a HuggingFace URL and it parses repo and filename
• VRAM hint is inferred from file size automatically
• Destination is inferred from asset type automatically
• Supports multiple quality variants per resource (fp16, fp8, q8, etc.)

generate

kulai generate WORKFLOW [--output FILE] [--mode auto|semi-auto] [--no-cache]

Parses a ComfyUI workflow JSON, resolves every asset, and writes a .kula file. Use --mode auto to skip the interactive review.

check

kulai check WORKFLOW [--verbose]

Scans local model directories and reports which assets are present and which are missing. No API calls, no downloads.

resolve

kulai resolve [WORKFLOW] [OPTIONS]

Option	Description
--auto	Skip prompts; use HIGH confidence resolutions only
--auto-all	Skip prompts; use all resolutions
--dry-run	Show what would be downloaded without downloading
--no-cache	Ignore cached mappings
--download-dir PATH	Override destination directory
--concurrent N	Parallel downloads (1–16)

config-init

kulai config-init [--software PROFILE]

First-time setup wizard. Supported software profiles: comfyui, a1111, forge, invokeai, swarmui.

cache-list / cache-clear

kulai cache-list
kulai cache-clear [NAME]

View or remove cached asset-to-source mappings.

config-show

kulai config-show

Print the active config with API keys redacted.

---

Civitai support

kulai supports both civitai.com and civitai.red (NSFW mirror) — paste URLs from either and the right API and download endpoint is used automatically.

Paste a model page URL in the wizard and kulai fetches metadata from the API:

https://civitai.com/models/971952/my-model?modelVersionId=1674551
https://civitai.red/models/123456/nsfw-model?modelVersionId=789012

When installing Civitai resources, .civitai.info sidecar files are saved alongside each model (ComfyUI Manager compatible). Disable with --no-civitai-info.

---

API keys

kulai works without API keys for most public models. Keys unlock extra access:

Key	Where to get it	What it unlocks
HuggingFace	huggingface.co/settings/tokens	Gated / private models
Civitai	civitai.com/user/account	Downloading (searching is free)

Set via environment variable:

# Linux / Mac
export KULAI_HF_TOKEN="hf_..."
export KULAI_CIVITAI_TOKEN="..."

# Windows PowerShell
$env:KULAI_HF_TOKEN="hf_..."
$env:KULAI_CIVITAI_TOKEN="..."

Or in the config file:

[api_keys]
huggingface = "hf_..."
civitai      = "..."

---

Configuration

Location:

• Linux / Mac: ~/.config/kulai/config.toml
• Windows: C:\Users\<you>\.config\kulai\config.toml

comfyui_dir = "C:/programs/ComfyUI"

# Model paths are inferred from comfyui_dir automatically.
# Uncomment to override individual paths:
# [paths]
# checkpoints   = "D:/models/checkpoints"
# loras         = "D:/models/loras"
# vae           = "D:/models/vae"
# text_encoders = "D:/models/text_encoders"
# unet          = "D:/models/unet"

[api_keys]
huggingface = ""
civitai      = ""

[download]
concurrent  = 2
max_retries = 3

[resolution]
preferred_source           = "huggingface"   # "huggingface" | "civitai" | "any"
auto_confidence_threshold  = "high"

---

Download features

• Concurrent downloads — configurable parallel transfers
• Resume support — picks up interrupted downloads where they left off
• SHA-256 verification — warns on mismatch, never silently deletes files
• Disk space check — warns before starting if space is tight
• Smart skipping — files already present are never re-downloaded
• Civitai.info sidecars — saves ComfyUI Manager compatible metadata alongside Civitai downloads

---

Supported asset types

Type	Default folder
Checkpoints	models/checkpoints
LoRAs / LyCORIS	models/loras
VAE	models/vae
Text encoders / CLIP	models/text_encoders
UNet / diffusion models	models/unet
ControlNet	models/controlnet
Upscale models	models/upscale_models
Embeddings	models/embeddings
IP-Adapter	models/ipadapter
Face restore / detection	models/facerestore_models

Path layout adapts per software profile (comfyui, a1111, forge, invokeai, swarmui).

---

Troubleshooting

"Gated model / access denied" Visit the model page on HuggingFace and request access, then retry.

"Civitai token required to download" Searching is free but downloading requires a token. Set KULAI_CIVITAI_TOKEN or add it to the config.

SHA-256 mismatch warning The file is kept. Run kulai cache-clear model.safetensors and re-resolve with --no-cache to try again.

Downloads are slow

kulai install workflow.kula --concurrent 4

---

Development

git clone https://github.com/BarkinMad/Kulai.git
cd Kulai
python -m venv .venv
.venv\Scripts\activate      # Windows
source .venv/bin/activate   # Linux / Mac
pip install -e .

pytest tests/ -v

---

License

MIT — see LICENSE for details.