Civitai-Downloader

KO | EN

gitlite — search

#python #hacktoberfest #react #go #android #deep-learning #docker #nodejs #java #cli #kubernetes #awesome-list #pytorch #openai

Civitai-Downloader

(★ 9)

Build your local Civitai library—plan, download, verify, resume, and catalog images, videos, models, and bundles.

Civitai-Downloader Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Civitai Downloader

Civitai Downloader is a policy-driven Python CLI for downloading Civitai image
and video resources, preserving approved generation metadata, and managing
bounded model and bundle workflows. It uses typed requests, explicit
confirmations, deterministic plans, resumable transfers, and a local catalog.
Bilingual terminal launchers provide a guided menu and safe first-run
environment bootstrap. A GUI is deferred until the CLI, catalog, and recovery
contracts are stable.

## Contents

- [Quick start](#quick-start)
  - [CLI and capabilities](#cli-and-capabilities)
  - [Bilingual launchers](#bilingual-launchers)
- [Scope and media workflow](#scope-and-media-workflow)
  - [Author, plan, and run](#author-plan-and-run)
  - [Targets, incremental runs, and scheduling](#targets-incremental-runs-and-scheduling)
  - [Metadata and recovery](#metadata-and-recovery)
- [Model assets and bundles](#model-assets-and-bundles)
  - [Manifest and verified download](#manifest-and-verified-download)
  - [Bundles and lifecycle](#bundles-and-lifecycle)
  - [Model-asset authoring and handoff](#model-asset-authoring-and-handoff)
- [Support and safety boundaries](#support-and-safety-boundaries)
  - [Filter boundary and migration](#filter-boundary-and-migration)
  - [Security and privacy](#security-and-privacy)
  - [Release and rollback](#release-and-rollback)

## Quick start

On a fresh checkout, start either launcher in the
[Bilingual launchers](#bilingual-launchers) section. It creates the fixed
project-local `.venv` when needed; use the direct CLI commands below after the
environment has been prepared.

### CLI and capabilities

Use the project-local CPython 3.13 environment:

```powershell
.venv\Scripts\python.exe -m civitai_downloader --help
.venv\Scripts\python.exe -m civitai_downloader scope validate path\to\scope.toml --json
.venv\Scripts\python.exe -m civitai_downloader scope show path\to\scope.toml --json
.venv\Scripts\python.exe -m civitai_downloader api capabilities --json
.venv\Scripts\python.exe -m civitai_downloader api media-capabilities --json
.venv\Scripts\python.exe -m civitai_downloader api model-capabilities --json
.venv\Scripts\python.exe -m civitai_downloader api model-transfer-capabilities --json
.venv\Scripts\python.exe -m civitai_downloader api bundle-capabilities --json
```

### Bilingual launchers

Both launchers use the same Python menu, action IDs, argument builder,
confirmations, and downloader implementation. Language selection is session-
only and supports Traditional Chinese (`zh-TW`) and English (`en-US`).

Windows:

```powershell
cmd /d /e:on /v:off /c .\civitai-downloader-menu.bat
```

Linux or macOS:

```sh
chmod +x ./civitai-downloader-menu.sh
./civitai-downloader-menu.sh
```

The launchers require an installed CPython 3.13+ base interpreter. If the
fixed project-local `.venv` is absent, they create it with copied interpreter
files, install this project and runtime dependencies in editable mode through
an isolated pip invocation, validate the result, and then start the menu. A
healthy `.venv` takes a fast path without reinstalling. If setup fails, the
menu is not started and launcher-owned partial state remains available for a
safe retry or manual repair. Development extras are not installed, and the
global/user environment is not modified.

Bootstrap does not contact Civitai, download asset bodies, or write catalog,
checkpoint, schedule, lease, or other application data. Linux execution is
verified; macOS is not currently verified. External symlink-based installation
layouts are not supported by the portable shell wrapper.

## Scope and media workflow

### Author, plan, and run

Create a bounded declarative scope, compile it, preview a fixture, and then
choose an explicit fixture or live provider:

```powershell
.venv\Scripts\python.exe -m civitai_downloader scope template --output authoring.toml
.venv\Scripts\python.exe -m civitai_downloader scope compile authoring.toml --output scope.toml --json
.venv\Scripts\python.exe -m civitai_downloader plan path\to\scope.toml --fixture path\to\fixture.json --json
.venv\Scripts\python.exe -m civitai_downloader run path\to\scope.toml --fixture path\to\fixture.json --catalog data\catalog.sqlite3 --json
```

Replace `--fixture PATH` with `--live` only for an explicitly selected live
provider. `plan --live` performs bounded discovery but does not download an
asset body or write catalog/checkpoint/schedule state. Commands without `--live`
never contact Civitai implicitly. Fixture and live inputs use the same typed
planner, transfer, metadata, catalog, and report contracts.

Media defaults to `image`. Select `video` or `mixed` consistently in both the
source selector and remote filter:

```toml
[[source.selectors]]
selector_type = "civitai"
resource_type = "video" # image, video, or mixed

[remote_filters]
media_type = "video"
```

Only MP4 and WebM are supported for video. Container verification is structural;
codec execution, playback, transcoding, audio downloads, and embedded-video
metadata parsing are unsupported. `mixed` creates explicit image and video
partitions that share the configured work limits.

### Targets, incremental runs, and scheduling

Target batches reuse the base ScopeV1 filters and add bounded target/page/item/
byte/runtime limits. They never broaden the base scope:

```powershell
.venv\Scripts\python.exe -m civitai_downloader targets validate scope.toml targets.toml --json
.venv\Scripts\python.exe -m civitai_downloader targets plan scope.toml targets.toml --fixture fixture.json --json
.venv\Scripts\python.exe -m civitai_downloader targets run scope.toml targets.toml --fixture fixture.json --catalog data\catalog.sqlite3 --json
```

For newest-first work, `incremental` persists selected work before advancing a
page checkpoint, so a later compatible run can resume retryable items:

```powershell
.venv\Scripts\python.exe -m civitai_downloader incremental path\to\scope.toml --fixture path\to\fixture.json --catalog data\catalog.sqlite3 --json
.venv\Scripts\python.exe -m civitai_downloader incremental path\to\scope.toml --live --catalog data\catalog.sqlite3 --json
```

Schedules use bounded interval or daily-at definitions, IANA time zones, and a
durable lease. The provider choice is bound into the schedule revision and a
mismatched fixture/live tick is rejected:

```powershell
.venv\Scripts\python.exe -m civitai_downloader schedule add path\to\scope.toml --catalog data\catalog.sqlite3 --provider fixture --kind interval --interval-seconds 3600 --json
.venv\Scripts\python.exe -m civitai_downloader schedule tick --catalog data\catalog.sqlite3 --scope path\to\scope.toml --fixture path\to\fixture.json --json
.venv\Scripts\python.exe -m civitai_downloader status --catalog data\catalog.sqlite3 --json
```

### Metadata and recovery

Metadata extraction is separate from selection and transfer. It can retain
bounded raw evidence, normalize supported A1111/ComfyUI fields, write an opt-in
JSON sidecar, and reprocess offline without downloading again. Prompts, signed
URLs, raw payloads, and private paths are not printed by default:

```powershell
.venv\Scripts\python.exe -m civitai_downloader metadata reprocess path\to\scope.toml --catalog data\catalog.sqlite3 --artifact-id 1 --json
.venv\Scripts\python.exe -m civitai_downloader catalog check --catalog data\catalog.sqlite3 --json
.venv\Scripts\python.exe -m civitai_downloader catalog backup --catalog data\catalog.sqlite3 --destination data\catalog.backup.sqlite3 --json
.venv\Scripts\python.exe -m civitai_downloader catalog restore --source data\catalog.backup.sqlite3 --destination data\catalog.restored.sqlite3 --confirm-restore --json
```

Use `retry` and `recover` for owned retryable work and partial files. Restore
into a separate path and verify it before re-enabling effects. Do not delete
user artifacts recursively or edit catalog tables by hand.

## Model assets and bundles

### Manifest and verified download

`ModelManifestRequestV1` is separate from ScopeV1 image-gallery filters. It
selects one exact model, one version, or a bounded public model list, then uses
`primary`, `all-public`, or exact `file-ids` selection. Synthetic examples are
provided in `examples/model_manifest_request_v1.toml` and
`examples/model_manifest_fixture_v1.json`:

```powershell
.venv\Scripts\python.exe -m civitai_downloader manifest validate examples\model_manifest_request_v1.toml --json
.venv\Scripts\python.exe -m civitai_downloader manifest plan examples\model_manifest_request_v1.toml --fixture examples\model_manifest_fixture_v1.json --json
.venv\Scripts\python.exe -m civitai_downloader manifest plan path\to\request.toml --live --json
```

Manifest planning is body-free. A selected manifest may be downloaded only
through an explicit live confirmation:

```powershell
.venv\Scripts\python.exe -m civitai_downloader manifest download path\to\request.toml --live --confirm-live --catalog data\catalog.sqlite3 --output-root downloads --json
```

Model weights require an authoritative SHA-256. Hashless attachments require
an explicit weaker-integrity opt-in. Redirects, unsafe ranges, changed
validators, insufficient disk reserve, checksum failures, and invalid
SafeTensor structures fail closed or are quarantined. Downloaded bytes are
never imported, executed, deserialized, or extracted.

### Bundles and lifecycle

`BundleRequestV1` composes model-file and image/video transfer engines under one
bounded disk, byte, item, runtime, retry, and concurrency envelope. Validate or
plan against the synthetic model fixture before an effectful command:

```powershell
.venv\Scripts\python.exe -m civitai_downloader bundle validate examples\bundle_request_v1.toml --json
.venv\Scripts\python.exe -m civitai_downloader bundle plan examples\bundle_request_v1.toml --fixture examples\model_manifest_fixture_v1.json --json
.venv\Scripts\python.exe -m civitai_downloader bundle download examples\bundle_request_v1.toml --live --confirm-live --catalog data\catalog.sqlite3 --output-root downloads --json
```

Lifecycle commands are:

```text
bundle pause|cancel BUNDLE_ID --catalog CATALOG
bundle resume|retry REQUEST --live --confirm-live --catalog CATALOG --output-root ROOT
bundle status BUNDLE_ID --catalog CATALOG
bundle installed --catalog CATALOG [--bundle-id BUNDLE_ID]
bundle verify BUNDLE_ID --catalog CATALOG --output-root ROOT
bundle updates REQUEST --live --catalog CATALOG
```

`status`, `installed`, and `verify` are local read-only queries. `updates`
performs bounded public manifest discovery and never installs or downloads an
update. Provenance sidecars contain allowlisted catalog facts and relative
paths only.

### Model-asset authoring and handoff

The bilingual authoring wizard creates one bounded canonical request with
explicit target, filter, file, access, integrity, destination, conflict, and
limit choices. It uses no-clobber writes, duplicate-key rejection, strict
lineage/readback validation, and typed corrections. See
[Model-asset authoring](docs/MODEL_ASSET_AUTHORING.md) for the fixed action IDs,
migration behavior, and privacy contract.

The `model` action family is deliberately narrower than direct manifest and
bundle commands: fixture-backed plans are synthetic, while live discovery,
detail/access, body transfer, installed-state inspection, and model automation
return typed fail-closed outcomes in this authoring boundary. Direct manifest
and bundle transfers retain their separate live confirmations.

## Support and safety boundaries

For exact resource, filter, platform, authoring, release, and security
contracts, see [Supported profiles](docs/SUPPORTED_PROFILES.md),
[Filter migration and troubleshooting](docs/FILTER_MIGRATION_AND_TROUBLESHOOTING.md),
[Model-asset authoring](docs/MODEL_ASSET_AUTHORING.md), [Release and rollback](docs/RELEASE_AND_ROLLBACK.md),
and [Security policy](SECURITY.md).

### Filter boundary and migration

Executable image/media filters come from
`civitai-official-image-filter-profile-v1`:

- source revision `72264a0b39e0340e1ad4afe26814ba8078fce1ac`;
- freshness revision `9d70ad348b011f54c71c5abdc4e431eaf5a0d57e`; and
- public route `https://civitai.com/api/v1/images`.

Supported sorts are `Newest`, `Oldest`, `Most Reactions`, `Most Comments`,
`Most Collected`, and `Random`. `Random` and ranked periods are manual-only
when stable automation ordering cannot be proved. `Most Downloaded` is a
legacy-readable migration value, not an executable filter. Followed, hidden,
scheduled, collection, and other auth-scoped or private website controls are
unsupported and remain inert. Use the
[filter migration and troubleshooting](docs/FILTER_MIGRATION_AND_TROUBLESHOOTING.md)
guide for refusal codes and safe recovery.

### Security and privacy

- Credentials are accepted only through the documented environment reference
  and exact approved origin; they are not written to requests, reports, or URLs.
- User- and server-derived paths are rooted, normalized, and checked for
  traversal, reserved names, links, and unsafe platform components.
- Downloads, archives, workflows, configuration files, and model content are
  inert data; they are not executed, imported, deserialized, or extracted.
- Logs and public artifacts omit prompts, raw metadata, signed URLs, cookies,
  tokens, private paths, and downloaded content by default.
- Audio, GUI, unknown formats, archive extraction, codec/model execution, and
  access-control bypass are outside the supported boundary.

Civitai-Downloader

Civitai-Downloader Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Civitai-Downloader

Civitai-Downloader Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README