Metadata

Comicarr pulls series and issue metadata from external databases and can embed that metadata directly into comic files using ComicTagger.

ComicVine

ComicVine is the primary metadata source. You need a free API key from the ComicVine website.

API Settings

Setting	Type	Default	Description
`CVAPI_RATE`	int	`2`	Maximum API requests per second. ComicVine's limit is 200/min; `2` per second is safe.
`CV_VERIFY`	bool	`True`	Verify TLS certificates for ComicVine API calls.
`CV_TIMEOUT`	int	`30`	Request timeout in seconds.
`CV_ONLY`	bool	`False`	Use ComicVine as the sole metadata source (disable all others).
`CV_ONETIMER`	bool	`False`	Run a single metadata refresh on startup, then stop.
`CV_USER_AGENT`	string	—	Custom User-Agent header for ComicVine requests. Leave blank for the default.

Caching

Comicarr caches ComicVine responses to reduce API calls and speed up repeated lookups.

Setting	Type	Default	Description
`CV_CACHE_ENABLED`	bool	`True`	Enable the ComicVine response cache.
`CV_CACHE_TTL_SEARCH`	int	`86400`	Cache TTL for search results in seconds (default: 24 hours).
`CV_CACHE_TTL_METADATA`	int	`604800`	Cache TTL for issue/series metadata in seconds (default: 7 days).
`CV_CACHE_TTL_ARC`	int	`259200`	Cache TTL for story arc data in seconds (default: 3 days).

Imprint Handling

Setting	Type	Default	Description
`CV_SKIP_IMPRINT_VALIDATION`	bool	`False`	Skip publisher imprint validation checks.
`IMPRINT_MAPPING_TYPE`	string	`CV`	Source for imprint-to-publisher mapping: `CV` (ComicVine) or `JSON` (local mapping file).

Parallel Requests

Setting	Type	Default	Description
`CV_PARALLEL_PAGINATION`	bool	`False`	Fetch multiple pages of results in parallel. Speeds up large series lookups.
`CV_MAX_PARALLEL_REQUESTS`	int	`3`	Maximum concurrent requests when parallel pagination is enabled.

Batch Limits

ComicVine may throttle or block accounts that make too many requests in a short window.

Setting	Type	Default	Description
`CV_BATCH_LIMIT_PROTECTION`	bool	`True`	Enable automatic throttling when approaching batch limits.
`CV_BATCH_LIMIT_THRESHOLD`	int	`200`	Number of requests in a batch window before throttling kicks in.

Disabling CV_BATCH_LIMIT_PROTECTION risks getting your API key temporarily blocked by ComicVine. Leave it enabled unless you have a specific reason.

Configure a list of publishers to exclude from metadata lookups. Issues from ignored publishers are skipped during searches and imports. This setting is managed through the UI on the Settings > Metadata page.

Metron

Metron is an alternative comic metadata database. It can supplement or replace ComicVine.

Setting	Type	Default	Description
`USE_METRON`	bool	`False`	Enable Metron as a metadata source.
`METRON_USERNAME`	string	—	Metron account username.
`METRON_PASSWORD`	string	—	Metron account password. Encrypted at rest.
`USE_METRON_SEARCH`	bool	`False`	Use Metron for search results in addition to metadata.

Comic Tagging

Comicarr can embed metadata directly into CBZ/CBR files using ComicTagger.

General

Setting	Type	Default	Description
`ENABLE_META`	bool	`False`	Enable comic file tagging.
`CMTAGGER_PATH`	string	—	Path to the ComicTagger binary. Leave blank if it is on `$PATH`.
`CBR2CBZ_ONLY`	bool	`False`	Only convert CBR to CBZ without writing metadata tags.
`UNRAR_CMD`	string	—	Path to the `unrar` binary, required for CBR conversion.

Tag Formats

Setting	Type	Default	Description
`CT_TAG_CR`	bool	`True`	Write ComicRack (CR) tags.
`CT_TAG_CBL`	bool	`False`	Write Comic Book Lover (CBL) tags.
`CT_CBZ_OVERWRITE`	bool	`False`	Overwrite existing tags in CBZ files.
`CT_NOTES_FORMAT`	string	—	Template for the Notes field in tagged files.

Volume Handling

Setting	Type	Default	Description
`CMTAG_VOLUME`	bool	`False`	Include the volume number in tags.
`CMTAG_START_YEAR_AS_VOLUME`	bool	`False`	Use the series start year as the volume number.
`SETDEFAULTVOLUME`	bool	`False`	Set volume to `1` when no volume information is available.