comic-dl's command-line interface. The default command downloads content when
given a URL.
comic-dl [OPTIONS]
comic-dl -u <URL> [OPTIONS]
comic-dl <URL> [OPTIONS]
comic-dl -f <FILE> [OPTIONS]
comic-dl <COMMAND> [ARGS]
| Command |
Description |
comic-dl -u <URL> |
Download a single gallery/series URL |
comic-dl <URL> |
Same as -u <URL> (positional shorthand) |
comic-dl -f <FILE> |
Download URLs from a text file (one per line) |
comic-dl (no args) |
Interactive prompt (requires a TTY) |
| Command |
Description |
comic-dl list [--json] [--source <DOMAIN>] |
List series in the library |
comic-dl info <SERIES> [--json] |
Show details for one series |
comic-dl latest [-n N] [--json] [--source <DOMAIN>] |
Chapters downloaded in the last N days (default 7) |
comic-dl update <SERIES|all> [-p N] [-c N] [--chapter-parallel N] [-q] [--compress ALG] [--format FMT] [--json] [--dry-run] |
Re-scrape tracked series, download new chapters. -p sets how many series update at once (1–16, default 1) |
comic-dl remove <SERIES> [-y/--yes] [--json] [--dry-run] |
Move a series to trash |
comic-dl restore <SERIES> [--json] [--dry-run] |
Bring a trashed series back |
update -p runs series concurrently but every request still passes through the
per-host rate limiter, so raising it never exceeds the politeness budget.
| Command |
Description |
comic-dl config path |
Print the effective config file path |
comic-dl config show |
Print resolved configuration (defaults + file) |
comic-dl config validate |
Type-check the file; report keys differing from defaults |
comic-dl config init [--force] |
Write a commented starter config |
comic-dl config edit |
Open config in $VISUAL / $EDITOR |
comic-dl config help |
Show help for the config commands |
| Command |
Description |
comic-dl cache status [--json] |
Show cache location, TTL, size budget, fresh/stale split |
comic-dl cache clear [-y] [--dry-run] [--json] |
Delete all cached entries (plus stray comic-dl-* temp dirs) |
comic-dl cache prune [-y] [--dry-run] [--json] |
Delete only stale (past TTL) and orphaned cache files |
comic-dl cookie ls [HOST] [--json] |
List stored cookies |
comic-dl cookie set <HOST> <NAME> <VALUE> [--expires <epoch>] |
Store a cookie |
comic-dl cookie clear [HOST] [-y] |
Clear cookies |
| Command |
Description |
comic-dl self version |
Print the installed version |
comic-dl self update [--check] [-y/--yes] [--channel beta] |
Check for and install updates through the tool that installed comic-dl |
comic-dl self site list [--json] |
List installed site adapters, their versions, and cached status |
comic-dl self site check [SITE] [--live] [--json] |
Compare installed adapter versions against the latest release manifest; --live runs a live check for one site |
comic-dl self site update [SITE] [--all] [-y/--yes] |
Update site support (bundled adapters update with the core) |
comic-dl plugin list [--json] |
List installed third-party sources (including broken ones) |
comic-dl plugin validate <PATH> |
Shape-check a plugin's Source class offline |
comic-dl plugin scaffold <NAME> [--domain HOST] |
Generate a plugin package skeleton |
self update refuses to guess: package-manager installs are updated by the
owning package manager, pip/uv installs by the tool that created them, and a
source checkout or unknown installation is reported with manual
instructions. See Self-Management and
Site Support for the per-installation behaviour.
| Command |
Description |
comic-dl --list-sources [--json] [--plugin] [QUERY] |
List/search supported sites |
comic-dl completion bash|zsh|fish|powershell |
Print shell completion script |
comic-dl --version |
Print the version |
comic-dl help [COMMAND] |
Show help |
help accepts subcommands, so comic-dl help self site prints the help for
self site rather than the top-level screen.
| Flag |
Short |
Default |
Description |
--url |
-u |
— |
Single URL to download |
--file |
-f |
— |
Text file with one URL per line |
| Flag |
Short |
Default |
Description |
--output |
-o |
~/Downloads/comic-dl |
Output directory |
--force |
|
|
Overwrite existing archives. With --file and multiple URLs, asks before re-downloading |
--dry-run |
|
|
Resolve each URL and list what would download, skip, or re-download, without writing |
--chapters |
|
interactive picker |
Chapter subset. 1-3,7 (1, 2, 3, 7), 1-3,7,10- (1, 2, 3, 7, 10 through the end), all, 0 (prologue/promo). Omit for a checkbox picker |
--max-image-size |
|
100MB |
Maximum bytes per image. Accepts suffixes (500MB, 2GB) |
--max-size |
|
0 (unlimited) |
Maximum total download size per batch; 0 also means unlimited |
--force is the only way to overwrite. Never overwriting is already the
default, so the old --no-clobber flag is a deprecated no-op and is no longer
listed on the help screen.
| Flag |
Short |
Default |
Description |
--concurrency |
-c |
5 |
Page images downloaded in parallel (1–32) |
--parallel |
|
5 |
Max URLs in flight across a batch (1–16) |
--chapter-parallel |
|
1 |
Max chapters of a series at once (1–8) |
--compress |
|
stored |
Compression: stored, deflate, deflate:0-9. Overrides [archive] |
--format |
|
cbz |
Archive format: cbz, zip, cbt. Overrides [archive] |
--format cbz is the most widely supported; zip and cbt are plain zip and
tar containers.
Size arguments accept suffixes — 500MB, 2GB, 512KB — or a plain integer,
which is read as bytes.
| Flag |
Default |
Description |
--impersonate |
chrome146 |
TLS/HTTP impersonation profile (e.g. chrome131). Overrides [http] |
--solver |
off |
Cloudflare challenge solver. Overrides [http]. auto tries impersonation first, then webview if needed; impersonation is TLS/HTTP fingerprint only; webview uses the system WebView (GTK/WebKit) and needs a display plus GTK libs; off disables the solver and challenged sites will fail. Solving is opt-in |
--proxy |
|
HTTP(S) proxy for every request (e.g. http://127.0.0.1:8080). Overrides $COMIC_DL_PROXY, $HTTPS_PROXY, [http] |
--no-cookie |
|
Disable the persistent cookie jar for this run |
--no-rate |
|
Disable per-site rate limiting for this run |
--no-cache |
|
Disable the on-disk scrape response cache for this run |
--no-generic |
|
Disable the generic fallback scraper, so unknown hosts report Unsupported URL instead of static extraction |
| Flag |
Short |
Default |
Description |
--quiet |
-q |
|
Suppress progress and status output; errors only (scripts/cron) |
--json |
|
|
Machine-readable JSON on stdout; disables interactive prompts |
--no-banner |
|
|
Suppress the ASCII brand banner |
--color |
|
auto |
auto honors NO_COLOR, CLICOLOR_FORCE, CLICOLOR, and FORCE_COLOR; use always for | less -R |
--no-color |
|
|
Disable ANSI colors everywhere, including progress |
| Flag |
Short |
Default |
Description |
--verbose |
-v |
|
Increase verbosity: -v context, -vv page/cover requests and timing, -vvv every image request and full trace |
--debug-file |
|
|
Divert the -vvv trace to a file instead of the screen (implies -vvv) |
--show-legal-notice |
|
|
Re-show the first-run legal notice, then continue |
COMIC_DL_TRACE_HTTP=1 shows page-request headers at -vv (images still need -vvv).
| Flag |
Short |
Description |
--config |
|
Path to a custom config.toml (overrides $COMIC_DL_CONFIG) |
--no-config |
|
Ignore config.toml for this run; built-in defaults only |
--quiet and --verbose are mutually exclusive.
Every --json payload includes a schema_version field (currently 2).
| Command |
Output shape |
comic-dl list --json |
{"schema_version": 2, "series": [...]} |
comic-dl latest --json |
{"schema_version": 2, "chapters": [...]} |
comic-dl info <S> --json |
{"schema_version": 2, ..., "chapters": [...]} |
comic-dl --list-sources --json |
{"schema_version": 2, "sources": [...]} |
comic-dl -u <URL> --json |
{"schema_version": 2, "url": ..., "status": "success"|"failed"|"skipped", ...} |
comic-dl -f <FILE> --json |
{"schema_version": 2, "urls": [...], "succeeded": N, "skipped": N, "failed": N, "partial": N} |
comic-dl update <S> --json |
{"schema_version": 2, "dry_run": false, "checked": N, "changed": N, "skipped": N, "failed": [...], "series": [...]} |
--json implies non-interactive mode and uses the same exit codes as the
human-facing run.
| Code |
Meaning |
0 |
Success |
1 |
Runtime error (download failed, network error) |
2 |
Invalid CLI usage (bad flag, bad value) |
130 |
Interrupted (Ctrl-C / SIGTERM) |
See Exit Codes for details.