civitai-hub 0.1.0

huggingface_hub but for CivitAI — inspect and download models/LoRAs

civitai-hub

huggingface_hub, but for CivitAI. Point it at a model URL to inspect what's inside (type, base/parent model, every file with sizes and hashes) and download the checkpoint or LoRA into a deduplicated, content-addressed cache — usable as both a CLI and an importable Python library.

$ civitai download https://civitai.com/models/580857 --fp16 -o ~/ComfyUI/models/loras
~/ComfyUI/models/loras/realistic-skin-xl.safetensors

Features

• Inspect before you fetch — civitai info <url> shows the model type, base/parent model, versions, and a table of every file (size, format, precision, hash, scan status).
• Smart, scriptable downloads — picks the URL-pinned version (or the latest) and its primary file by default; override with --version-id, --fp16/--fp32, --pruned/--full, --format, --file, or grab everything with --all.
• Find the base model — civitai base <lora-url> lists the checkpoints a LoRA's base-model family runs on (CivitAI only exposes the family name, not a direct link), with --download N to grab one.
• Managed cache like HF Hub — content-addressed blobs keyed by SHA256, with per-version snapshot symlinks. The same file reused across versions is stored once. Re-downloads are skipped.
• Resumable & verified — HTTP range-resume for interrupted downloads, automatic SHA256 verification, and a live progress bar.
• Library + CLI — everything the CLI does is a one-line call from Python.
• Safe by default — blocks files flagged unsafe by CivitAI's scanners (override with --allow-unscanned) and fails fast on early-access/gated content with a clear message.

Install

pipx install civitai-hub        # isolated CLI (recommended)
# or
pip install civitai-hub         # into the current environment

For development from a clone:

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

CLI quickstart

# Inspect a model (human table, or --json for machines)
civitai info https://civitai.com/models/580857/realistic-skin
civitai info 580857 --json

# Download the primary file of the latest (or URL-pinned) version
civitai download https://civitai.com/models/580857

# Drop a specific precision straight into your ComfyUI/A1111 folder
civitai download 580857 --fp16 -o ~/ComfyUI/models/loras

# Preview what would be fetched without downloading
civitai download 580857 --dry-run

# Grab every file in the version
civitai download 580857 --all

# Find the base checkpoints a LoRA runs on, then grab one
civitai base 580857
civitai base 580857 --download 1 -o ~/ComfyUI/models/checkpoints

The downloaded path is printed to stdout (the progress bar goes to stderr), so it pipes cleanly:

MODEL=$(civitai download 580857 --no-progress)

Library usage

import civitai_hub

# Inspect
info = civitai_hub.model_info("https://civitai.com/models/580857")
print(info.model.type, info.version.base_model, len(info.files))

# Download — returns the local Path (or list[Path] with all=True)
path = civitai_hub.download(
    "https://civitai.com/models/580857",
    fp="fp16",
    local_dir="~/ComfyUI/models/loras",
)

download(...) mirrors hf_hub_download (single file) and snapshot_download (all=True).

Authentication

Most public files download without a token. For gated, NSFW, or early-access resources, create an API key in your CivitAI account settings and provide it via:

export CIVITAI_TOKEN=<your key>     # or pass --token <key>

Configuration

Precedence is flag → environment variable → default.

Setting	Flag	Env var	Default
API token	--token	CIVITAI_TOKEN	(anonymous)
Cache root	--cache-dir	CIVITAI_HOME	platform cache dir (~/.cache/civitai on Linux)
Offline (cache only)	—	CIVITAI_OFFLINE	off
Copy instead of symlink	--no-symlinks	CIVITAI_DISABLE_SYMLINKS	symlinks on
Disable progress bar	--no-progress	CIVITAI_NO_PROGRESS	progress on

How it works

A model URL resolves to one GET /api/v1/models/{id} call; the version is the URL's pinned modelVersionId (or the latest published one), and the file is that version's primary .safetensors unless you filter it. Downloads stream the signed CDN URL with ?token= (CivitAI strips the Authorization header on the cross-domain redirect), verify SHA256, and land in the cache:

$CIVITAI_HOME/
└── models/<modelId>/
    ├── blobs/<sha256>                      # content-addressed, deduplicated
    └── snapshots/<versionId>/<filename>    # symlink → ../../blobs/<sha256>

--local-dir then materializes a symlink (or copy) of the blob into the folder you choose.

For the full command/flag reference, cache details, troubleshooting, and exit codes, see docs/usage.md.

Docker

Prebuilt multi-arch images are published to the GitHub Container Registry on every release:

# inspect a model
docker run --rm ghcr.io/mr8bit/civit-ai-cli info 580857

# download into a host folder (mount it as the cache + output)
docker run --rm -v "$PWD/models:/data" \
  ghcr.io/mr8bit/civit-ai-cli download 580857 -o /data

# pass a token for gated content
docker run --rm -e CIVITAI_TOKEN="$CIVITAI_TOKEN" \
  ghcr.io/mr8bit/civit-ai-cli base 580857

The cache lives at /data inside the image (CIVITAI_HOME) — mount a volume there to persist downloads. Build it yourself with docker build -t civitai-hub ..

Development

pip install -e ".[dev]"
pytest                 # full suite (offline; httpx mocked with respx)
pytest tests/test_resolver.py::test_fp_selector -v   # a single test
ruff check src tests   # lint
CIVITAI_LIVE=1 pytest tests/test_live.py -v           # opt-in test against the real API

See CONTRIBUTING.md for the architecture overview and conventions, and docs/superpowers/specs/ + docs/superpowers/plans/ for the original design and implementation plan.

License

MIT © Artemiy Mazaew