Loading search…

Explain with AI
Open in ChatGPT(opens in a new tab)Open in Claude(opens in a new tab)Open in Perplexity(opens in a new tab)Open in Duck.ai(opens in a new tab)

Opens your own AI account with the prompt ready. comic-dl sends nothing itself.

Edit this page

CLI Reference

Last updated

Every command and flag in comic-dl, plus JSON output and exit codes.

On this page

Look up commands, flags, defaults, and JSON output shapes. The default command downloads content when given a URL; see Downloading for worked examples.

Synopsis

comic-dl [OPTIONS]
comic-dl -u <URL> [OPTIONS]
comic-dl <URL> [OPTIONS]
comic-dl -f <FILE> [OPTIONS]
comic-dl <COMMAND> [ARGS]

Commands

Download

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)

Library

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] [--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> [--dry-run] Move a series to trash
comic-dl restore <SERIES> 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.

Configuration

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

Cache & Cookies

Command Description
comic-dl cache status [--json] Show cache location, TTL, size budget, fresh/stale split
comic-dl cache clear [-y] [--dry-run] Delete all cached entries (plus stray comic-dl-* temp dirs)
comic-dl cache prune [-y] [--dry-run] 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> Store a cookie
comic-dl cookie clear [HOST] [-y] Clear cookies

Self & plugins

Command Description
comic-dl self version Print the installed version
comic-dl self update [--check] [-y] [--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 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.

Inspect & integrate

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.

Global flags

Input

Flag Short Default Description
--url -u — Single URL to download
--file -f — Text file with one URL per line

Layout & output

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.

Download tuning

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.

HTTP & politeness

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

Output

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

Diagnostics

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).

Config

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.

JSON output

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.

Exit codes

Code Meaning
0 Success
1 Runtime error (download failed, network error)
2 Invalid CLI usage (bad flag, bad value)
130 Interrupted (Ctrl-C / SIGTERM)