# Environment Variables

This document lists all configuration options that can be set via environment variables.

> **Auto-generated** - Do not edit manually. Run `python scripts/generate_env_docs.py` to regenerate.

## Table of Contents

- [Bootstrap Configuration](#bootstrap-configuration)
- [General](#general)
- [Search Mode](#search-mode)
- [Downloads](#downloads)
- [Security](#security)
- [Network](#network)
- [Advanced](#advanced)
- [Prowlarr](#prowlarr)
- [AudiobookBay](#audiobookbay)
- [IRC](#irc)
- [Download Clients](#download-clients)
- [Metadata Providers](#metadata-providers)
  - [Hardcover](#metadata-providers-hardcover)
  - [Open Library](#metadata-providers-open-library)
  - [Google Books](#metadata-providers-google-books)

- [Direct Download](#direct-download)
  - [Download Sources](#direct-download-download-sources)
  - [Cloudflare Bypass](#direct-download-cloudflare-bypass)
  - [Mirrors](#direct-download-mirrors)

---

## Bootstrap Configuration

These environment variables are used at startup before the settings system loads. They typically configure paths and server settings.

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `CONFIG_DIR` | Directory for storing configuration files and plugin settings. | string (path) | `/config` |
| `LOG_ROOT` | Root directory for log files. | string (path) | `/var/log/` |
| `TMP_DIR` | Staging directory for downloads before moving to destination. | string (path) | `/tmp/shelfmark` |
| `ENABLE_LOGGING` | Enable file logging under LOG_ROOT/shelfmark/ (including shelfmark.log and startup logs). | boolean | `true` |
| `FLASK_HOST` | Host address for the Flask web server. | string | `0.0.0.0` |
| `FLASK_PORT` | Port number for the Flask web server. | number | `8084` |
| `SESSION_COOKIE_SECURE` | Enable secure cookies (requires HTTPS). | boolean | `false` |
| `CWA_DB_PATH` | Path to the Calibre-Web database for authentication integration. | string (path) | `/auth/app.db` |
| `DOCKERMODE` | Indicates the application is running inside a Docker container. | boolean | `false` |
| `ONBOARDING` | Show the onboarding wizard on first run. Set to false to skip (useful for ephemeral storage). | boolean | `true` |

<details>
<summary>Detailed descriptions</summary>

#### `CONFIG_DIR`

Directory for storing configuration files and plugin settings.

- **Type:** string (path)
- **Default:** `/config`

#### `LOG_ROOT`

Root directory for log files.

- **Type:** string (path)
- **Default:** `/var/log/`

#### `TMP_DIR`

Staging directory for downloads before moving to destination.

- **Type:** string (path)
- **Default:** `/tmp/shelfmark`

#### `ENABLE_LOGGING`

Enable file logging under LOG_ROOT/shelfmark/ (including shelfmark.log and startup logs).

- **Type:** boolean
- **Default:** `true`

#### `FLASK_HOST`

Host address for the Flask web server.

- **Type:** string
- **Default:** `0.0.0.0`

#### `FLASK_PORT`

Port number for the Flask web server.

- **Type:** number
- **Default:** `8084`

#### `SESSION_COOKIE_SECURE`

Enable secure cookies (requires HTTPS).

- **Type:** boolean
- **Default:** `false`

#### `CWA_DB_PATH`

Path to the Calibre-Web database for authentication integration.

- **Type:** string (path)
- **Default:** `/auth/app.db`

#### `DOCKERMODE`

Indicates the application is running inside a Docker container.

- **Type:** boolean
- **Default:** `false`

#### `ONBOARDING`

Show the onboarding wizard on first run. Set to false to skip (useful for ephemeral storage).

- **Type:** boolean
- **Default:** `true`

</details>

## General

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `CALIBRE_WEB_URL` | Adds a navigation button to your book library (Calibre-Web Automated, Booklore, etc). | string | _none_ |
| `AUDIOBOOK_LIBRARY_URL` | Adds a separate navigation button for your audiobook library (Audiobookshelf, Plex, etc). When both URLs are set, icons are shown instead of text. | string | _none_ |
| `SUPPORTED_FORMATS` | Book formats to include in search results. ZIP/RAR archives are extracted automatically and book files are used if found. | string (comma-separated) | `epub,mobi,azw3,fb2,djvu,cbz,cbr` |
| `SUPPORTED_AUDIOBOOK_FORMATS` | Audiobook formats to include in search results. ZIP/RAR archives are extracted automatically and audiobook files are used if found. | string (comma-separated) | `m4b,mp3` |
| `BOOK_LANGUAGE` | Default language filter for searches. | string (comma-separated) | `en` |

<details>
<summary>Detailed descriptions</summary>

#### `CALIBRE_WEB_URL`

**Library URL**

Adds a navigation button to your book library (Calibre-Web Automated, Booklore, etc).

- **Type:** string
- **Default:** _none_

#### `AUDIOBOOK_LIBRARY_URL`

**Audiobook Library URL**

Adds a separate navigation button for your audiobook library (Audiobookshelf, Plex, etc). When both URLs are set, icons are shown instead of text.

- **Type:** string
- **Default:** _none_

#### `SUPPORTED_FORMATS`

**Supported Book Formats**

Book formats to include in search results. ZIP/RAR archives are extracted automatically and book files are used if found.

- **Type:** string (comma-separated)
- **Default:** `epub,mobi,azw3,fb2,djvu,cbz,cbr`

#### `SUPPORTED_AUDIOBOOK_FORMATS`

**Supported Audiobook Formats**

Audiobook formats to include in search results. ZIP/RAR archives are extracted automatically and audiobook files are used if found.

- **Type:** string (comma-separated)
- **Default:** `m4b,mp3`

#### `BOOK_LANGUAGE`

**Default Book Languages**

Default language filter for searches.

- **Type:** string (comma-separated)
- **Default:** `en`

</details>

## Search Mode

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `SEARCH_MODE` | How you want to search for and download books. | string (choice) | `direct` |
| `AA_DEFAULT_SORT` | Default sort order for search results. | string (choice) | `relevance` |
| `SHOW_RELEASE_SOURCE_LINKS` | Show clickable release-source links in release and details modals. Metadata provider links stay enabled. | boolean | `true` |
| `METADATA_PROVIDER` | Choose which metadata provider to use for book searches. | string (choice) | `openlibrary` |
| `METADATA_PROVIDER_AUDIOBOOK` | Metadata provider for audiobook searches. Uses the book provider if not set. | string (choice) | _empty string_ |
| `DEFAULT_RELEASE_SOURCE` | The release source tab to open by default in the release modal for books. | string (choice) | `direct_download` |
| `DEFAULT_RELEASE_SOURCE_AUDIOBOOK` | The release source tab to open by default in the release modal for audiobooks. Uses the book release source if not set. | string (choice) | _empty string_ |

<details>
<summary>Detailed descriptions</summary>

#### `SEARCH_MODE`

**Search Mode**

How you want to search for and download books.

- **Type:** string (choice)
- **Default:** `direct`
- **Options:** `direct` (Direct), `universal` (Universal)

#### `AA_DEFAULT_SORT`

**Default Sort Order**

Default sort order for search results.

- **Type:** string (choice)
- **Default:** `relevance`
- **Options:** `relevance` (Most relevant), `newest` (Newest (publication year)), `oldest` (Oldest (publication year)), `largest` (Largest (filesize)), `smallest` (Smallest (filesize)), `newest_added` (Newest (open sourced)), `oldest_added` (Oldest (open sourced))

#### `SHOW_RELEASE_SOURCE_LINKS`

**Show Release Source Links**

Show clickable release-source links in release and details modals. Metadata provider links stay enabled.

- **Type:** boolean
- **Default:** `true`

#### `METADATA_PROVIDER`

**Book Metadata Provider**

Choose which metadata provider to use for book searches.

- **Type:** string (choice)
- **Default:** `openlibrary`
- **Options:** `hardcover` (Hardcover), `openlibrary` (Open Library), `googlebooks` (Google Books)

#### `METADATA_PROVIDER_AUDIOBOOK`

**Audiobook Metadata Provider**

Metadata provider for audiobook searches. Uses the book provider if not set.

- **Type:** string (choice)
- **Default:** _empty string_
- **Options:** `""` (Use book provider), `hardcover` (Hardcover), `openlibrary` (Open Library), `googlebooks` (Google Books)

#### `DEFAULT_RELEASE_SOURCE`

**Default Book Release Source**

The release source tab to open by default in the release modal for books.

- **Type:** string (choice)
- **Default:** `direct_download`
- **Options:** `direct_download` (Direct Download), `prowlarr` (Prowlarr)

#### `DEFAULT_RELEASE_SOURCE_AUDIOBOOK`

**Default Audiobook Release Source**

The release source tab to open by default in the release modal for audiobooks. Uses the book release source if not set.

- **Type:** string (choice)
- **Default:** _empty string_
- **Options:** `""` (Use book release source), `prowlarr` (Prowlarr), `audiobookbay` (AudiobookBay)

</details>

## Downloads

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `BOOKS_OUTPUT_MODE` | Choose where completed book files are sent. | string (choice) | `folder` |
| `INGEST_DIR` | Directory where downloaded files are saved. Use {User} for per-user folders (e.g. /books/{User}). | string | `/books` |
| `FILE_ORGANIZATION` | Choose how downloaded book files are named and organized. | string (choice) | `rename` |
| `TEMPLATE_RENAME` | Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads. | string | `{Author} - {Title} ({Year})` |
| `TEMPLATE_ORGANIZE` | Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. | string | `{Author}/{Title} ({Year})` |
| `HARDLINK_TORRENTS` | Create hardlinks instead of copying. Preserves seeding but archives won't be extracted. Don't use if destination is a library ingest folder. | boolean | `false` |
| `BOOKLORE_HOST` | Base URL of your Booklore instance | string | _none_ |
| `BOOKLORE_USERNAME` | Booklore account username | string | _none_ |
| `BOOKLORE_PASSWORD` | Booklore account password | string (secret) | _none_ |
| `BOOKLORE_DESTINATION` | Choose whether uploads go directly to a specific library path or to Bookdrop for review. | string (choice) | `library` |
| `BOOKLORE_LIBRARY_ID` | Booklore library to upload into. | string (choice) | _none_ |
| `BOOKLORE_PATH_ID` | Booklore library path for uploads. | string (choice) | _none_ |
| `EMAIL_RECIPIENT` | Optional fallback email address when no per-user email recipient override is configured. | string | _none_ |
| `EMAIL_ATTACHMENT_SIZE_LIMIT_MB` | Maximum total attachment size per email. Email encoding adds overhead; keep this below your provider's limit. | number | `25` |
| `EMAIL_SMTP_HOST` | SMTP server hostname or IP (e.g., smtp.gmail.com). | string | _none_ |
| `EMAIL_SMTP_PORT` | SMTP server port (587 is typical for STARTTLS, 465 for SSL). | number | `587` |
| `EMAIL_SMTP_SECURITY` | Transport security mode for SMTP. | string (choice) | `starttls` |
| `EMAIL_SMTP_USERNAME` | SMTP username (leave empty for no authentication). | string | _none_ |
| `EMAIL_SMTP_PASSWORD` | SMTP password (required if Username is set). | string (secret) | _none_ |
| `EMAIL_FROM` | From address used for the email. You can include a display name (e.g., Shelfmark <mail@example.com>). Leave blank to default to the SMTP username (when it is an email address). | string | _none_ |
| `EMAIL_SUBJECT_TEMPLATE` | Email subject. Variables: {Author}, {Title}, {Year}, {Series}, {SeriesPosition}, {Subtitle}, {Format}. | string | `{Title}` |
| `EMAIL_SMTP_TIMEOUT_SECONDS` | How long to wait for SMTP operations before failing. | number | `60` |
| `EMAIL_ALLOW_UNVERIFIED_TLS` | Disable TLS certificate verification (not recommended). | boolean | `false` |
| `DESTINATION_AUDIOBOOK` | Directory where downloaded audiobook files are saved. Leave empty to use the Books destination. | string | _none_ |
| `FILE_ORGANIZATION_AUDIOBOOK` | Choose how downloaded audiobook files are named and organized. | string (choice) | `rename` |
| `TEMPLATE_AUDIOBOOK_RENAME` | Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads. | string | `{Author} - {Title}` |
| `TEMPLATE_AUDIOBOOK_ORGANIZE` | Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. | string | `{Author}/{Title}` |
| `HARDLINK_TORRENTS_AUDIOBOOK` | Create hardlinks instead of copying. Preserves seeding but archives won't be extracted. Don't use if destination is a library ingest folder. | boolean | `true` |
| `AUTO_OPEN_DOWNLOADS_SIDEBAR` | Automatically open the downloads sidebar when a new download is queued. | boolean | `false` |
| `DOWNLOAD_TO_BROWSER_CONTENT_TYPES` | Automatically download completed files to your browser for the selected content types. | string (comma-separated) | _empty list_ |
| `MAX_CONCURRENT_DOWNLOADS` | Maximum number of simultaneous downloads. | number | `3` |
| `STATUS_TIMEOUT` | How long to keep completed/failed downloads in the queue display. | number | `3600` |

<details>
<summary>Detailed descriptions</summary>

#### `BOOKS_OUTPUT_MODE`

**Output Mode**

Choose where completed book files are sent.

- **Type:** string (choice)
- **Default:** `folder`
- **Options:** `folder` (Folder), `email` (Email (SMTP)), `booklore` (Booklore (API))

#### `INGEST_DIR`

**Destination**

Directory where downloaded files are saved. Use {User} for per-user folders (e.g. /books/{User}).

- **Type:** string
- **Default:** `/books`
- **Required:** Yes

#### `FILE_ORGANIZATION`

**File Organization**

Choose how downloaded book files are named and organized. 

- **Type:** string (choice)
- **Default:** `rename`
- **Options:** `none` (None), `rename` (Rename Only), `organize` (Rename and Organize)

#### `TEMPLATE_RENAME`

**Naming Template**

Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads.

- **Type:** string
- **Default:** `{Author} - {Title} ({Year})`

#### `TEMPLATE_ORGANIZE`

**Path Template**

Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.

- **Type:** string
- **Default:** `{Author}/{Title} ({Year})`

#### `HARDLINK_TORRENTS`

**Hardlink Book Torrents**

Create hardlinks instead of copying. Preserves seeding but archives won't be extracted. Don't use if destination is a library ingest folder.

- **Type:** boolean
- **Default:** `false`

#### `BOOKLORE_HOST`

**Booklore URL**

Base URL of your Booklore instance

- **Type:** string
- **Default:** _none_
- **Required:** Yes

#### `BOOKLORE_USERNAME`

**Username**

Booklore account username

- **Type:** string
- **Default:** _none_
- **Required:** Yes

#### `BOOKLORE_PASSWORD`

**Password**

Booklore account password

- **Type:** string (secret)
- **Default:** _none_
- **Required:** Yes

#### `BOOKLORE_DESTINATION`

**Upload Destination**

Choose whether uploads go directly to a specific library path or to Bookdrop for review.

- **Type:** string (choice)
- **Default:** `library`
- **Options:** `library` (Specific Library), `bookdrop` (Bookdrop)

#### `BOOKLORE_LIBRARY_ID`

**Library**

Booklore library to upload into.

- **Type:** string (choice)
- **Default:** _none_
- **Required:** Yes

#### `BOOKLORE_PATH_ID`

**Path**

Booklore library path for uploads.

- **Type:** string (choice)
- **Default:** _none_
- **Required:** Yes

#### `EMAIL_RECIPIENT`

**Default Email Recipient**

Optional fallback email address when no per-user email recipient override is configured.

- **Type:** string
- **Default:** _none_

#### `EMAIL_ATTACHMENT_SIZE_LIMIT_MB`

**Attachment Size Limit (MB)**

Maximum total attachment size per email. Email encoding adds overhead; keep this below your provider's limit.

- **Type:** number
- **Default:** `25`
- **Constraints:** min: 1, max: 600

#### `EMAIL_SMTP_HOST`

**SMTP Host**

SMTP server hostname or IP (e.g., smtp.gmail.com).

- **Type:** string
- **Default:** _none_
- **Required:** Yes

#### `EMAIL_SMTP_PORT`

**SMTP Port**

SMTP server port (587 is typical for STARTTLS, 465 for SSL).

- **Type:** number
- **Default:** `587`
- **Constraints:** min: 1, max: 65535

#### `EMAIL_SMTP_SECURITY`

**SMTP Security**

Transport security mode for SMTP.

- **Type:** string (choice)
- **Default:** `starttls`
- **Options:** `none` (None), `starttls` (STARTTLS), `ssl` (SSL/TLS)

#### `EMAIL_SMTP_USERNAME`

**Username**

SMTP username (leave empty for no authentication).

- **Type:** string
- **Default:** _none_

#### `EMAIL_SMTP_PASSWORD`

**Password**

SMTP password (required if Username is set).

- **Type:** string (secret)
- **Default:** _none_

#### `EMAIL_FROM`

**From Address**

From address used for the email. You can include a display name (e.g., Shelfmark <mail@example.com>). Leave blank to default to the SMTP username (when it is an email address).

- **Type:** string
- **Default:** _none_

#### `EMAIL_SUBJECT_TEMPLATE`

**Subject Template**

Email subject. Variables: {Author}, {Title}, {Year}, {Series}, {SeriesPosition}, {Subtitle}, {Format}.

- **Type:** string
- **Default:** `{Title}`

#### `EMAIL_SMTP_TIMEOUT_SECONDS`

**SMTP Timeout (seconds)**

How long to wait for SMTP operations before failing.

- **Type:** number
- **Default:** `60`
- **Constraints:** min: 1, max: 600

#### `EMAIL_ALLOW_UNVERIFIED_TLS`

**Allow Unverified TLS**

Disable TLS certificate verification (not recommended).

- **Type:** boolean
- **Default:** `false`

#### `DESTINATION_AUDIOBOOK`

**Destination**

Directory where downloaded audiobook files are saved. Leave empty to use the Books destination.

- **Type:** string
- **Default:** _none_

#### `FILE_ORGANIZATION_AUDIOBOOK`

**File Organization**

Choose how downloaded audiobook files are named and organized.

- **Type:** string (choice)
- **Default:** `rename`
- **Options:** `none` (None), `rename` (Rename Only), `organize` (Rename and Organize)

#### `TEMPLATE_AUDIOBOOK_RENAME`

**Naming Template**

Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or '\'); use Organize for folders. Applies to single-file downloads.

- **Type:** string
- **Default:** `{Author} - {Title}`

#### `TEMPLATE_AUDIOBOOK_ORGANIZE`

**Path Template**

Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.

- **Type:** string
- **Default:** `{Author}/{Title}`

#### `HARDLINK_TORRENTS_AUDIOBOOK`

**Hardlink Audiobook Torrents**

Create hardlinks instead of copying. Preserves seeding but archives won't be extracted. Don't use if destination is a library ingest folder.

- **Type:** boolean
- **Default:** `true`

#### `AUTO_OPEN_DOWNLOADS_SIDEBAR`

**Auto-Open Downloads Sidebar**

Automatically open the downloads sidebar when a new download is queued.

- **Type:** boolean
- **Default:** `false`

#### `DOWNLOAD_TO_BROWSER_CONTENT_TYPES`

**Download to Browser**

Automatically download completed files to your browser for the selected content types.

- **Type:** string (comma-separated)
- **Default:** _empty list_

#### `MAX_CONCURRENT_DOWNLOADS`

**Max Concurrent Downloads**

Maximum number of simultaneous downloads.

- **Type:** number
- **Default:** `3`
- **Requires restart:** Yes
- **Constraints:** min: 1, max: 10

#### `STATUS_TIMEOUT`

**Status Timeout (seconds)**

How long to keep completed/failed downloads in the queue display.

- **Type:** number
- **Default:** `3600`
- **Constraints:** min: 60, max: 86400

</details>

## Security

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `AUTH_METHOD` | Select the authentication method for accessing Shelfmark. | string (choice) | `none` |
| `PROXY_AUTH_USER_HEADER` | The HTTP header your proxy uses to pass the authenticated username. | string | `X-Auth-User` |
| `PROXY_AUTH_LOGOUT_URL` | The URL to redirect users to for logging out. Leave empty to disable logout functionality. | string | _empty string_ |
| `PROXY_AUTH_ADMIN_GROUP_HEADER` | Optional: header your proxy uses to pass user groups/roles. | string | `X-Auth-Groups` |
| `PROXY_AUTH_ADMIN_GROUP_NAME` | Optional: users in this group are treated as admins. Leave blank to skip group-based admin detection. | string | _empty string_ |
| `OIDC_DISCOVERY_URL` | OpenID Connect discovery endpoint URL. Usually ends with /.well-known/openid-configuration. | string | _none_ |
| `OIDC_CLIENT_ID` | OAuth2 client ID from your identity provider. | string | _none_ |
| `OIDC_CLIENT_SECRET` | OAuth2 client secret from your identity provider. | string (secret) | _none_ |
| `OIDC_SCOPES` | OAuth2 scopes to request from the identity provider. Managed automatically: includes essential scopes and the group claim when using admin group authorization. | string | `openid,email,profile` |
| `OIDC_GROUP_CLAIM` | The name of the claim in the ID token that contains user groups. | string | `groups` |
| `OIDC_ADMIN_GROUP` | Users in this group will be given admin access (if enabled below). Leave empty to use database roles only. | string | _empty string_ |
| `OIDC_USE_ADMIN_GROUP` | When enabled, users in the Admin Group are granted admin access. When disabled, admin access is determined solely by database roles. | boolean | `true` |
| `OIDC_AUTO_PROVISION` | Automatically create a user account on first OIDC login. When disabled, users must be pre-created by an admin. | boolean | `true` |
| `OIDC_BUTTON_LABEL` | Custom label for the OIDC sign-in button on the login page. | string | _empty string_ |

<details>
<summary>Detailed descriptions</summary>

#### `AUTH_METHOD`

**Authentication Method**

Select the authentication method for accessing Shelfmark.

- **Type:** string (choice)
- **Default:** `none`
- **Options:** `none` (No Authentication), `builtin` (Local), `proxy` (Proxy Authentication), `oidc` (OIDC (OpenID Connect)), `cwa` (Calibre-Web Database)

#### `PROXY_AUTH_USER_HEADER`

**Proxy Auth User Header**

The HTTP header your proxy uses to pass the authenticated username.

- **Type:** string
- **Default:** `X-Auth-User`

#### `PROXY_AUTH_LOGOUT_URL`

**Proxy Auth Logout URL**

The URL to redirect users to for logging out. Leave empty to disable logout functionality.

- **Type:** string
- **Default:** _empty string_

#### `PROXY_AUTH_ADMIN_GROUP_HEADER`

**Proxy Auth Admin Group Header**

Optional: header your proxy uses to pass user groups/roles.

- **Type:** string
- **Default:** `X-Auth-Groups`

#### `PROXY_AUTH_ADMIN_GROUP_NAME`

**Proxy Auth Admin Group**

Optional: users in this group are treated as admins. Leave blank to skip group-based admin detection.

- **Type:** string
- **Default:** _empty string_

#### `OIDC_DISCOVERY_URL`

**Discovery URL**

OpenID Connect discovery endpoint URL. Usually ends with /.well-known/openid-configuration.

- **Type:** string
- **Default:** _none_
- **Required:** Yes

#### `OIDC_CLIENT_ID`

**Client ID**

OAuth2 client ID from your identity provider.

- **Type:** string
- **Default:** _none_
- **Required:** Yes

#### `OIDC_CLIENT_SECRET`

**Client Secret**

OAuth2 client secret from your identity provider.

- **Type:** string (secret)
- **Default:** _none_
- **Required:** Yes

#### `OIDC_SCOPES`

**Scopes**

OAuth2 scopes to request from the identity provider. Managed automatically: includes essential scopes and the group claim when using admin group authorization.

- **Type:** string
- **Default:** `openid,email,profile`

#### `OIDC_GROUP_CLAIM`

**Group Claim Name**

The name of the claim in the ID token that contains user groups.

- **Type:** string
- **Default:** `groups`

#### `OIDC_ADMIN_GROUP`

**Admin Group Name**

Users in this group will be given admin access (if enabled below). Leave empty to use database roles only.

- **Type:** string
- **Default:** _empty string_

#### `OIDC_USE_ADMIN_GROUP`

**Use Admin Group for Authorization**

When enabled, users in the Admin Group are granted admin access. When disabled, admin access is determined solely by database roles.

- **Type:** boolean
- **Default:** `true`

#### `OIDC_AUTO_PROVISION`

**Auto-Provision Users**

Automatically create a user account on first OIDC login. When disabled, users must be pre-created by an admin.

- **Type:** boolean
- **Default:** `true`

#### `OIDC_BUTTON_LABEL`

**Login Button Label**

Custom label for the OIDC sign-in button on the login page.

- **Type:** string
- **Default:** _empty string_

</details>

## Network

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `CERTIFICATE_VALIDATION` | Controls SSL/TLS certificate verification for outbound connections. Disable for self-signed certificates on internal services (e.g. OIDC providers, Prowlarr). | string (choice) | `enabled` |
| `CUSTOM_DNS` | DNS provider for domain resolution. 'Auto' rotates through providers on failure. | string (choice) | `auto` |
| `CUSTOM_DNS_MANUAL` | Comma-separated list of DNS server IP addresses (e.g., 8.8.8.8, 1.1.1.1). | string | _none_ |
| `USE_DOH` | Use encrypted DNS queries for improved reliability and privacy. | boolean | `true` |
| `USING_TOR` | Route all traffic through Tor for enhanced privacy. | boolean | `false` |
| `PROXY_MODE` | Choose proxy type. SOCKS5 handles all traffic through a single proxy. | string (choice) | `none` |
| `HTTP_PROXY` | HTTP proxy URL (e.g., http://proxy:8080) | string | _none_ |
| `HTTPS_PROXY` | HTTPS proxy URL (leave empty to use HTTP proxy for HTTPS) | string | _none_ |
| `SOCKS5_PROXY` | SOCKS5 proxy URL. Supports auth: socks5://user:pass@host:port | string | _none_ |
| `NO_PROXY` | Comma-separated hosts to bypass proxy (e.g., localhost,127.0.0.1,10.*,*.local) | string | _none_ |

<details>
<summary>Detailed descriptions</summary>

#### `CERTIFICATE_VALIDATION`

**Certificate Validation**

Controls SSL/TLS certificate verification for outbound connections. Disable for self-signed certificates on internal services (e.g. OIDC providers, Prowlarr).

- **Type:** string (choice)
- **Default:** `enabled`
- **Options:** `enabled` (Enabled (Recommended)), `disabled_local` (Disabled for Local Addresses), `disabled` (Disabled)

#### `CUSTOM_DNS`

**DNS Provider**

DNS provider for domain resolution. 'Auto' rotates through providers on failure.

- **Type:** string (choice)
- **Default:** `auto`
- **Options:** `auto` (Auto (Recommended)), `system` (System), `google` (Google), `cloudflare` (Cloudflare), `quad9` (Quad9), `opendns` (OpenDNS), `manual` (Manual)

#### `CUSTOM_DNS_MANUAL`

**Manual DNS Servers**

Comma-separated list of DNS server IP addresses (e.g., 8.8.8.8, 1.1.1.1).

- **Type:** string
- **Default:** _none_

#### `USE_DOH`

**Use DNS over HTTPS**

Use encrypted DNS queries for improved reliability and privacy.

- **Type:** boolean
- **Default:** `true`

#### `USING_TOR`

**Tor Routing**

Route all traffic through Tor for enhanced privacy.

- **Type:** boolean
- **Default:** `false`

#### `PROXY_MODE`

**Proxy Mode**

Choose proxy type. SOCKS5 handles all traffic through a single proxy.

- **Type:** string (choice)
- **Default:** `none`
- **Options:** `none` (None (Direct Connection)), `http` (HTTP/HTTPS Proxy), `socks5` (SOCKS5 Proxy)

#### `HTTP_PROXY`

**HTTP Proxy**

HTTP proxy URL (e.g., http://proxy:8080)

- **Type:** string
- **Default:** _none_

#### `HTTPS_PROXY`

**HTTPS Proxy**

HTTPS proxy URL (leave empty to use HTTP proxy for HTTPS)

- **Type:** string
- **Default:** _none_

#### `SOCKS5_PROXY`

**SOCKS5 Proxy**

SOCKS5 proxy URL. Supports auth: socks5://user:pass@host:port

- **Type:** string
- **Default:** _none_

#### `NO_PROXY`

**No Proxy**

Comma-separated hosts to bypass proxy (e.g., localhost,127.0.0.1,10.*,*.local)

- **Type:** string
- **Default:** _none_

</details>

## Advanced

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `URL_BASE` | Optional URL path prefix. Use a path like /shelfmark (no hostname). Leave blank for root. | string | _none_ |
| `DEBUG` | Enable verbose logging to console and file. Not recommended for normal use. | boolean | `false` |
| `MAIN_LOOP_SLEEP_TIME` | How often the download queue is checked for new items. | number | `5` |
| `DOWNLOAD_PROGRESS_UPDATE_INTERVAL` | How often download progress is broadcast to the UI. | number | `1` |
| `CUSTOM_SCRIPT` | Path to a script to run after each successful download. Must be executable. | string | _none_ |
| `CUSTOM_SCRIPT_PATH_MODE` | Pass the path to the custom script as an absolute path or relative to the destination folder. | string (choice) | `absolute` |
| `CUSTOM_SCRIPT_JSON_PAYLOAD` | Send a JSON payload to the script via stdin. Useful for multi-file imports (audiobooks) or richer metadata without relying on path parsing. | boolean | `false` |
| `COVERS_CACHE_ENABLED` | Cache book covers on the server for faster loading. | boolean | `true` |
| `COVERS_CACHE_TTL` | How long to keep cached covers. Set to 0 to keep forever (recommended for static artwork). | number | `0` |
| `COVERS_CACHE_MAX_SIZE_MB` | Maximum disk space for cached covers. Oldest images are removed when limit is reached. | number | `500` |
| `METADATA_CACHE_ENABLED` | When disabled, all metadata searches hit the provider API directly. | boolean | `true` |
| `METADATA_CACHE_SEARCH_TTL` | How long to cache search results. Default: 300 (5 minutes). Max: 604800 (7 days). | number | `300` |
| `METADATA_CACHE_BOOK_TTL` | How long to cache individual book details. Default: 600 (10 minutes). Max: 604800 (7 days). | number | `600` |

<details>
<summary>Detailed descriptions</summary>

#### `URL_BASE`

**Base Path**

Optional URL path prefix. Use a path like /shelfmark (no hostname). Leave blank for root.

- **Type:** string
- **Default:** _none_
- **Requires restart:** Yes

#### `DEBUG`

**Debug Mode**

Enable verbose logging to console and file. Not recommended for normal use.

- **Type:** boolean
- **Default:** `false`
- **Requires restart:** Yes

#### `MAIN_LOOP_SLEEP_TIME`

**Queue Check Interval (seconds)**

How often the download queue is checked for new items.

- **Type:** number
- **Default:** `5`
- **Requires restart:** Yes
- **Constraints:** min: 1, max: 60

#### `DOWNLOAD_PROGRESS_UPDATE_INTERVAL`

**Progress Update Interval (seconds)**

How often download progress is broadcast to the UI.

- **Type:** number
- **Default:** `1`
- **Requires restart:** Yes
- **Constraints:** min: 1, max: 10

#### `CUSTOM_SCRIPT`

**Custom Script Path**

Path to a script to run after each successful download. Must be executable.

- **Type:** string
- **Default:** _none_

#### `CUSTOM_SCRIPT_PATH_MODE`

**Custom Script Path Mode**

Pass the path to the custom script as an absolute path or relative to the destination folder.

- **Type:** string (choice)
- **Default:** `absolute`
- **Options:** `absolute` (Absolute), `relative` (Relative)

#### `CUSTOM_SCRIPT_JSON_PAYLOAD`

**Custom Script JSON Payload**

Send a JSON payload to the script via stdin. Useful for multi-file imports (audiobooks) or richer metadata without relying on path parsing.

- **Type:** boolean
- **Default:** `false`

#### `COVERS_CACHE_ENABLED`

**Enable Cover Cache**

Cache book covers on the server for faster loading.

- **Type:** boolean
- **Default:** `true`

#### `COVERS_CACHE_TTL`

**Cache TTL (days)**

How long to keep cached covers. Set to 0 to keep forever (recommended for static artwork).

- **Type:** number
- **Default:** `0`
- **Constraints:** min: 0, max: 365

#### `COVERS_CACHE_MAX_SIZE_MB`

**Max Cache Size (MB)**

Maximum disk space for cached covers. Oldest images are removed when limit is reached.

- **Type:** number
- **Default:** `500`
- **Constraints:** min: 50, max: 5000

#### `METADATA_CACHE_ENABLED`

**Enable Metadata Caching**

When disabled, all metadata searches hit the provider API directly.

- **Type:** boolean
- **Default:** `true`

#### `METADATA_CACHE_SEARCH_TTL`

**Search Results Cache (seconds)**

How long to cache search results. Default: 300 (5 minutes). Max: 604800 (7 days).

- **Type:** number
- **Default:** `300`
- **Constraints:** min: 60, max: 604800

#### `METADATA_CACHE_BOOK_TTL`

**Book Details Cache (seconds)**

How long to cache individual book details. Default: 600 (10 minutes). Max: 604800 (7 days).

- **Type:** number
- **Default:** `600`
- **Constraints:** min: 60, max: 604800

</details>

## Prowlarr

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `PROWLARR_ENABLED` | Enable searching for books via Prowlarr indexers | boolean | `false` |
| `PROWLARR_URL` | Base URL of your Prowlarr instance | string | _none_ |
| `PROWLARR_API_KEY` | Found in Prowlarr: Settings > General > API Key | string (secret) | _none_ |
| `PROWLARR_INDEXERS` | Select which indexers to search. 📚 = has book categories. Leave empty to search all. | string (comma-separated) | _empty list_ |
| `PROWLARR_AUTO_EXPAND` | Automatically retry search without category filtering if no results are found | boolean | `false` |

<details>
<summary>Detailed descriptions</summary>

#### `PROWLARR_ENABLED`

**Enable Prowlarr source**

Enable searching for books via Prowlarr indexers

- **Type:** boolean
- **Default:** `false`

#### `PROWLARR_URL`

**Prowlarr URL**

Base URL of your Prowlarr instance

- **Type:** string
- **Default:** _none_
- **Required:** Yes

#### `PROWLARR_API_KEY`

**API Key**

Found in Prowlarr: Settings > General > API Key

- **Type:** string (secret)
- **Default:** _none_
- **Required:** Yes

#### `PROWLARR_INDEXERS`

**Indexers to Search**

Select which indexers to search. 📚 = has book categories. Leave empty to search all.

- **Type:** string (comma-separated)
- **Default:** _empty list_

#### `PROWLARR_AUTO_EXPAND`

**Auto-expand search on no results**

Automatically retry search without category filtering if no results are found

- **Type:** boolean
- **Default:** `false`

</details>

## AudiobookBay

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `ABB_ENABLED` | Enable AudiobookBay as a release source for audiobooks. | boolean | `false` |
| `ABB_HOSTNAME` | AudiobookBay domain (e.g., audiobookbay.lu, audiobookbay.is). Required to enable searches. | string | _empty string_ |
| `ABB_PAGE_LIMIT` | Maximum number of search result pages to fetch (1-10). | number | `1` |
| `ABB_EXACT_PHRASE` | Wrap generated queries in quotes for stricter matching. If no results are found, Shelfmark retries without quotes. | boolean | `false` |
| `ABB_RATE_LIMIT_DELAY` | Delay between requests in seconds to avoid rate limiting (0-10). | number | `1.0` |

<details>
<summary>Detailed descriptions</summary>

#### `ABB_ENABLED`

**Enable AudiobookBay**

Enable AudiobookBay as a release source for audiobooks.

- **Type:** boolean
- **Default:** `false`

#### `ABB_HOSTNAME`

**Hostname**

AudiobookBay domain (e.g., audiobookbay.lu, audiobookbay.is). Required to enable searches.

- **Type:** string
- **Default:** _empty string_
- **Required:** Yes

#### `ABB_PAGE_LIMIT`

**Max Pages to Search**

Maximum number of search result pages to fetch (1-10).

- **Type:** number
- **Default:** `1`
- **Constraints:** min: 1, max: 10

#### `ABB_EXACT_PHRASE`

**Prefer Exact-Phrase Search**

Wrap generated queries in quotes for stricter matching. If no results are found, Shelfmark retries without quotes.

- **Type:** boolean
- **Default:** `false`

#### `ABB_RATE_LIMIT_DELAY`

**Rate Limit Delay (seconds)**

Delay between requests in seconds to avoid rate limiting (0-10).

- **Type:** number
- **Default:** `1.0`
- **Constraints:** min: 0.0, max: 10.0

</details>

## IRC

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `IRC_SERVER` | IRC server hostname | string | _none_ |
| `IRC_PORT` | IRC server port (usually 6697 for TLS, 6667 for plain) | number | `6697` |
| `IRC_USE_TLS` | Enable TLS/SSL encryption for the IRC connection. Disable for servers that don't support TLS. | boolean | `true` |
| `IRC_CHANNEL` | Channel name without the # prefix | string | _none_ |
| `IRC_NICK` | Your IRC nickname (required). Must be unique on the IRC network. | string | _none_ |
| `IRC_SEARCH_BOT` | The search bot to query for results | string | _none_ |
| `IRC_CACHE_TTL` | How long to keep cached search results before they expire. | string (choice) | `2592000` |

<details>
<summary>Detailed descriptions</summary>

#### `IRC_SERVER`

**Server**

IRC server hostname

- **Type:** string
- **Default:** _none_
- **Required:** Yes

#### `IRC_PORT`

**Port**

IRC server port (usually 6697 for TLS, 6667 for plain)

- **Type:** number
- **Default:** `6697`

#### `IRC_USE_TLS`

**Use TLS**

Enable TLS/SSL encryption for the IRC connection. Disable for servers that don't support TLS.

- **Type:** boolean
- **Default:** `true`

#### `IRC_CHANNEL`

**Channel**

Channel name without the # prefix

- **Type:** string
- **Default:** _none_
- **Required:** Yes

#### `IRC_NICK`

**Nickname**

Your IRC nickname (required). Must be unique on the IRC network.

- **Type:** string
- **Default:** _none_
- **Required:** Yes

#### `IRC_SEARCH_BOT`

**Search bot**

The search bot to query for results

- **Type:** string
- **Default:** _none_

#### `IRC_CACHE_TTL`

**Cache Duration**

How long to keep cached search results before they expire.

- **Type:** string (choice)
- **Default:** `2592000`
- **Options:** `2592000` (30 days), `0` (Forever (until manually cleared))

</details>

## Download Clients

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `PROWLARR_TORRENT_CLIENT` | Choose which torrent client to use | string (choice) | _empty string_ |
| `QBITTORRENT_URL` | Web UI URL of your qBittorrent instance | string | _none_ |
| `QBITTORRENT_USERNAME` | qBittorrent Web UI username | string | _none_ |
| `QBITTORRENT_PASSWORD` | qBittorrent Web UI password | string (secret) | _none_ |
| `QBITTORRENT_CATEGORY` | Category to assign to book downloads in qBittorrent | string | `books` |
| `QBITTORRENT_CATEGORY_AUDIOBOOK` | Category for audiobook downloads. Leave empty to use the book category. | string | _empty string_ |
| `QBITTORRENT_DOWNLOAD_DIR` | Server-side directory where torrents are downloaded (optional, uses qBittorrent default if not specified) | string | _none_ |
| `QBITTORRENT_TAG` | Tag(s) to assign to qBittorrent downloads. Leave empty for no tags. | string | _empty list_ |
| `TRANSMISSION_URL` | URL of your Transmission instance (use https:// for TLS) | string | _none_ |
| `TRANSMISSION_USERNAME` | Transmission RPC username (if authentication enabled) | string | _none_ |
| `TRANSMISSION_PASSWORD` | Transmission RPC password | string (secret) | _none_ |
| `TRANSMISSION_CATEGORY` | Label to assign to book downloads in Transmission | string | `books` |
| `TRANSMISSION_CATEGORY_AUDIOBOOK` | Label for audiobook downloads. Leave empty to use the book label. | string | _empty string_ |
| `TRANSMISSION_DOWNLOAD_DIR` | Server-side directory where torrents are downloaded (optional, uses Transmission default if not specified) | string | _none_ |
| `DELUGE_HOST` | Hostname/IP or full URL of your Deluge Web UI (deluge-web) | string | `localhost` |
| `DELUGE_PORT` | Deluge Web UI port (default: 8112) | string | `8112` |
| `DELUGE_PASSWORD` | Deluge Web UI password (default: deluge) | string (secret) | _none_ |
| `DELUGE_CATEGORY` | Label to assign to book downloads in Deluge | string | `books` |
| `DELUGE_CATEGORY_AUDIOBOOK` | Label for audiobook downloads. Leave empty to use the book label. | string | _empty string_ |
| `DELUGE_DOWNLOAD_DIR` | Server-side directory where torrents are downloaded (optional, uses Deluge default if not specified) | string | _none_ |
| `RTORRENT_URL` | XML-RPC URL of your rTorrent instance | string | _none_ |
| `RTORRENT_USERNAME` | HTTP Basic auth username (if authentication enabled) | string | _none_ |
| `RTORRENT_PASSWORD` | HTTP Basic auth password | string (secret) | _none_ |
| `RTORRENT_LABEL` | Label to assign to book downloads in rTorrent | string | `cwabd` |
| `RTORRENT_DOWNLOAD_DIR` | Server-side directory where torrents are downloaded (optional, uses rTorrent default if not specified) | string | _none_ |
| `PROWLARR_TORRENT_ACTION` | Remove deletes the torrent from your client immediately after import (stops seeding, files are kept); Keep leaves it in the client to continue seeding | string (choice) | `keep` |
| `PROWLARR_USENET_CLIENT` | Choose which usenet client to use | string (choice) | _empty string_ |
| `NZBGET_URL` | URL of your NZBGet instance | string | _none_ |
| `NZBGET_USERNAME` | NZBGet control username | string | `nzbget` |
| `NZBGET_PASSWORD` | NZBGet control password | string (secret) | _none_ |
| `NZBGET_CATEGORY` | Category to assign to book downloads in NZBGet | string | `Books` |
| `NZBGET_CATEGORY_AUDIOBOOK` | Category for audiobook downloads. Leave empty to use the book category. | string | _empty string_ |
| `SABNZBD_URL` | URL of your SABnzbd instance | string | _none_ |
| `SABNZBD_API_KEY` | Found in SABnzbd: Config > General > API Key | string (secret) | _none_ |
| `SABNZBD_CATEGORY` | Category to assign to book downloads in SABnzbd | string | `books` |
| `SABNZBD_CATEGORY_AUDIOBOOK` | Category for audiobook downloads. Leave empty to use the book category. | string | _empty string_ |
| `PROWLARR_USENET_ACTION` | Move deletes the job from your usenet client after import; Copy keeps it in the client | string (choice) | `move` |

<details>
<summary>Detailed descriptions</summary>

#### `PROWLARR_TORRENT_CLIENT`

**Torrent Client**

Choose which torrent client to use

- **Type:** string (choice)
- **Default:** _empty string_
- **Options:** `""` (None), `qbittorrent` (qBittorrent), `transmission` (Transmission), `deluge` (Deluge), `rtorrent` (rTorrent)

#### `QBITTORRENT_URL`

**qBittorrent URL**

Web UI URL of your qBittorrent instance

- **Type:** string
- **Default:** _none_

#### `QBITTORRENT_USERNAME`

**Username**

qBittorrent Web UI username

- **Type:** string
- **Default:** _none_

#### `QBITTORRENT_PASSWORD`

**Password**

qBittorrent Web UI password

- **Type:** string (secret)
- **Default:** _none_

#### `QBITTORRENT_CATEGORY`

**Book Category**

Category to assign to book downloads in qBittorrent

- **Type:** string
- **Default:** `books`

#### `QBITTORRENT_CATEGORY_AUDIOBOOK`

**Audiobook Category**

Category for audiobook downloads. Leave empty to use the book category.

- **Type:** string
- **Default:** _empty string_

#### `QBITTORRENT_DOWNLOAD_DIR`

**Download Directory**

Server-side directory where torrents are downloaded (optional, uses qBittorrent default if not specified)

- **Type:** string
- **Default:** _none_

#### `QBITTORRENT_TAG`

**Tags**

Tag(s) to assign to qBittorrent downloads. Leave empty for no tags.

- **Type:** string
- **Default:** _empty list_

#### `TRANSMISSION_URL`

**Transmission URL**

URL of your Transmission instance (use https:// for TLS)

- **Type:** string
- **Default:** _none_

#### `TRANSMISSION_USERNAME`

**Username**

Transmission RPC username (if authentication enabled)

- **Type:** string
- **Default:** _none_

#### `TRANSMISSION_PASSWORD`

**Password**

Transmission RPC password

- **Type:** string (secret)
- **Default:** _none_

#### `TRANSMISSION_CATEGORY`

**Book Label**

Label to assign to book downloads in Transmission

- **Type:** string
- **Default:** `books`

#### `TRANSMISSION_CATEGORY_AUDIOBOOK`

**Audiobook Label**

Label for audiobook downloads. Leave empty to use the book label.

- **Type:** string
- **Default:** _empty string_

#### `TRANSMISSION_DOWNLOAD_DIR`

**Download Directory**

Server-side directory where torrents are downloaded (optional, uses Transmission default if not specified)

- **Type:** string
- **Default:** _none_

#### `DELUGE_HOST`

**Deluge Web UI Host/URL**

Hostname/IP or full URL of your Deluge Web UI (deluge-web)

- **Type:** string
- **Default:** `localhost`

#### `DELUGE_PORT`

**Deluge Web UI Port**

Deluge Web UI port (default: 8112)

- **Type:** string
- **Default:** `8112`

#### `DELUGE_PASSWORD`

**Password**

Deluge Web UI password (default: deluge)

- **Type:** string (secret)
- **Default:** _none_

#### `DELUGE_CATEGORY`

**Book Label**

Label to assign to book downloads in Deluge

- **Type:** string
- **Default:** `books`

#### `DELUGE_CATEGORY_AUDIOBOOK`

**Audiobook Label**

Label for audiobook downloads. Leave empty to use the book label.

- **Type:** string
- **Default:** _empty string_

#### `DELUGE_DOWNLOAD_DIR`

**Download Directory**

Server-side directory where torrents are downloaded (optional, uses Deluge default if not specified)

- **Type:** string
- **Default:** _none_

#### `RTORRENT_URL`

**rTorrent URL**

XML-RPC URL of your rTorrent instance

- **Type:** string
- **Default:** _none_

#### `RTORRENT_USERNAME`

**Username**

HTTP Basic auth username (if authentication enabled)

- **Type:** string
- **Default:** _none_

#### `RTORRENT_PASSWORD`

**Password**

HTTP Basic auth password

- **Type:** string (secret)
- **Default:** _none_

#### `RTORRENT_LABEL`

**Book Label**

Label to assign to book downloads in rTorrent

- **Type:** string
- **Default:** `cwabd`

#### `RTORRENT_DOWNLOAD_DIR`

**Download Directory**

Server-side directory where torrents are downloaded (optional, uses rTorrent default if not specified)

- **Type:** string
- **Default:** _none_

#### `PROWLARR_TORRENT_ACTION`

**Torrent Completion Action**

Remove deletes the torrent from your client immediately after import (stops seeding, files are kept); Keep leaves it in the client to continue seeding

- **Type:** string (choice)
- **Default:** `keep`
- **Options:** `keep` (Keep), `remove` (Remove)

#### `PROWLARR_USENET_CLIENT`

**Usenet Client**

Choose which usenet client to use

- **Type:** string (choice)
- **Default:** _empty string_
- **Options:** `""` (None), `nzbget` (NZBGet), `sabnzbd` (SABnzbd)

#### `NZBGET_URL`

**NZBGet URL**

URL of your NZBGet instance

- **Type:** string
- **Default:** _none_

#### `NZBGET_USERNAME`

**Username**

NZBGet control username

- **Type:** string
- **Default:** `nzbget`

#### `NZBGET_PASSWORD`

**Password**

NZBGet control password

- **Type:** string (secret)
- **Default:** _none_

#### `NZBGET_CATEGORY`

**Book Category**

Category to assign to book downloads in NZBGet

- **Type:** string
- **Default:** `Books`

#### `NZBGET_CATEGORY_AUDIOBOOK`

**Audiobook Category**

Category for audiobook downloads. Leave empty to use the book category.

- **Type:** string
- **Default:** _empty string_

#### `SABNZBD_URL`

**SABnzbd URL**

URL of your SABnzbd instance

- **Type:** string
- **Default:** _none_

#### `SABNZBD_API_KEY`

**API Key**

Found in SABnzbd: Config > General > API Key

- **Type:** string (secret)
- **Default:** _none_

#### `SABNZBD_CATEGORY`

**Book Category**

Category to assign to book downloads in SABnzbd

- **Type:** string
- **Default:** `books`

#### `SABNZBD_CATEGORY_AUDIOBOOK`

**Audiobook Category**

Category for audiobook downloads. Leave empty to use the book category.

- **Type:** string
- **Default:** _empty string_

#### `PROWLARR_USENET_ACTION`

**NZB Completion Action**

Move deletes the job from your usenet client after import; Copy keeps it in the client

- **Type:** string (choice)
- **Default:** `move`
- **Options:** `move` (Move), `copy` (Copy)

</details>

## Metadata Providers

### Metadata Providers: Hardcover

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `HARDCOVER_ENABLED` | Enable Hardcover as a metadata provider for book searches | boolean | `false` |
| `HARDCOVER_API_KEY` | Get your API key from hardcover.app/account/api | string (secret) | _none_ |
| `HARDCOVER_DEFAULT_SORT` | Default sort order for Hardcover search results. | string (choice) | `relevance` |
| `HARDCOVER_EXCLUDE_COMPILATIONS` | Filter out compilations, anthologies, and omnibus editions from search results | boolean | `false` |
| `HARDCOVER_EXCLUDE_UNRELEASED` | Filter out books with a release year in the future | boolean | `false` |

<details>
<summary>Detailed descriptions</summary>

#### `HARDCOVER_ENABLED`

**Enable Hardcover**

Enable Hardcover as a metadata provider for book searches

- **Type:** boolean
- **Default:** `false`

#### `HARDCOVER_API_KEY`

**API Key**

Get your API key from hardcover.app/account/api

- **Type:** string (secret)
- **Default:** _none_
- **Required:** Yes

#### `HARDCOVER_DEFAULT_SORT`

**Default Sort Order**

Default sort order for Hardcover search results.

- **Type:** string (choice)
- **Default:** `relevance`
- **Options:** `relevance` (Most relevant), `popularity` (Most popular), `rating` (Highest rated), `newest` (Newest), `oldest` (Oldest)

#### `HARDCOVER_EXCLUDE_COMPILATIONS`

**Exclude Compilations**

Filter out compilations, anthologies, and omnibus editions from search results

- **Type:** boolean
- **Default:** `false`

#### `HARDCOVER_EXCLUDE_UNRELEASED`

**Exclude Unreleased Books**

Filter out books with a release year in the future

- **Type:** boolean
- **Default:** `false`

</details>

### Metadata Providers: Open Library

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `OPENLIBRARY_ENABLED` | Enable Open Library as a metadata provider for book searches | boolean | `false` |
| `OPENLIBRARY_DEFAULT_SORT` | Default sort order for Open Library search results. | string (choice) | `relevance` |

<details>
<summary>Detailed descriptions</summary>

#### `OPENLIBRARY_ENABLED`

**Enable Open Library**

Enable Open Library as a metadata provider for book searches

- **Type:** boolean
- **Default:** `false`

#### `OPENLIBRARY_DEFAULT_SORT`

**Default Sort Order**

Default sort order for Open Library search results.

- **Type:** string (choice)
- **Default:** `relevance`
- **Options:** `relevance` (Most relevant), `newest` (Newest), `oldest` (Oldest)

</details>

### Metadata Providers: Google Books

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `GOOGLEBOOKS_ENABLED` | Enable Google Books as a metadata provider for book searches | boolean | `false` |
| `GOOGLEBOOKS_API_KEY` | Get your API key from Google Cloud Console (APIs & Services > Credentials) | string (secret) | _none_ |
| `GOOGLEBOOKS_DEFAULT_SORT` | Default sort order for Google Books search results. | string (choice) | `relevance` |

<details>
<summary>Detailed descriptions</summary>

#### `GOOGLEBOOKS_ENABLED`

**Enable Google Books**

Enable Google Books as a metadata provider for book searches

- **Type:** boolean
- **Default:** `false`

#### `GOOGLEBOOKS_API_KEY`

**API Key**

Get your API key from Google Cloud Console (APIs & Services > Credentials)

- **Type:** string (secret)
- **Default:** _none_
- **Required:** Yes

#### `GOOGLEBOOKS_DEFAULT_SORT`

**Default Sort Order**

Default sort order for Google Books search results.

- **Type:** string (choice)
- **Default:** `relevance`
- **Options:** `relevance` (Most relevant), `newest` (Newest)

</details>

## Direct Download

### Direct Download: Download Sources

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `AA_DONATOR_KEY` | Enables fast download access on AA. Get this from your donator account page. | string (secret) | _none_ |
| `FAST_SOURCES_DISPLAY` | Always tried first, no waiting or bypass required. | JSON array | _see UI for defaults_ |
| `SOURCE_PRIORITY` | Fallback sources, may have waiting. Requires bypasser. Drag to reorder. | JSON array | _see UI for defaults_ |
| `MAX_RETRY` | Maximum retry attempts for failed downloads. | number | `10` |
| `DEFAULT_SLEEP` | Wait time between download retry attempts. | number | `5` |
| `AA_CONTENT_TYPE_ROUTING` | Override destination based on content type metadata. | boolean | `false` |
| `AA_CONTENT_TYPE_DIR_FICTION` | Fiction Books | string | _none_ |
| `AA_CONTENT_TYPE_DIR_NON_FICTION` | Non-Fiction Books | string | _none_ |
| `AA_CONTENT_TYPE_DIR_UNKNOWN` | Unknown Books | string | _none_ |
| `AA_CONTENT_TYPE_DIR_MAGAZINE` | Magazines | string | _none_ |
| `AA_CONTENT_TYPE_DIR_COMIC` | Comic Books | string | _none_ |
| `AA_CONTENT_TYPE_DIR_STANDARDS` | Standards Documents | string | _none_ |
| `AA_CONTENT_TYPE_DIR_MUSICAL_SCORE` | Musical Scores | string | _none_ |
| `AA_CONTENT_TYPE_DIR_OTHER` | Other | string | _none_ |

<details>
<summary>Detailed descriptions</summary>

#### `AA_DONATOR_KEY`

**Account Donator Key**

Enables fast download access on AA. Get this from your donator account page.

- **Type:** string (secret)
- **Default:** _none_

#### `FAST_SOURCES_DISPLAY`

**Fast downloads**

Always tried first, no waiting or bypass required.

- **Type:** JSON array
- **Default:** _see UI for defaults_

#### `SOURCE_PRIORITY`

**Slow downloads**

Fallback sources, may have waiting. Requires bypasser. Drag to reorder.

- **Type:** JSON array
- **Default:** _see UI for defaults_

#### `MAX_RETRY`

**Max Retries**

Maximum retry attempts for failed downloads.

- **Type:** number
- **Default:** `10`
- **Constraints:** min: 1, max: 50

#### `DEFAULT_SLEEP`

**Retry Delay (seconds)**

Wait time between download retry attempts.

- **Type:** number
- **Default:** `5`
- **Constraints:** min: 1, max: 60

#### `AA_CONTENT_TYPE_ROUTING`

**Enable Content-Type Routing**

Override destination based on content type metadata.

- **Type:** boolean
- **Default:** `false`

#### `AA_CONTENT_TYPE_DIR_FICTION`

**Fiction Books**

- **Type:** string
- **Default:** _none_

#### `AA_CONTENT_TYPE_DIR_NON_FICTION`

**Non-Fiction Books**

- **Type:** string
- **Default:** _none_

#### `AA_CONTENT_TYPE_DIR_UNKNOWN`

**Unknown Books**

- **Type:** string
- **Default:** _none_

#### `AA_CONTENT_TYPE_DIR_MAGAZINE`

**Magazines**

- **Type:** string
- **Default:** _none_

#### `AA_CONTENT_TYPE_DIR_COMIC`

**Comic Books**

- **Type:** string
- **Default:** _none_

#### `AA_CONTENT_TYPE_DIR_STANDARDS`

**Standards Documents**

- **Type:** string
- **Default:** _none_

#### `AA_CONTENT_TYPE_DIR_MUSICAL_SCORE`

**Musical Scores**

- **Type:** string
- **Default:** _none_

#### `AA_CONTENT_TYPE_DIR_OTHER`

**Other**

- **Type:** string
- **Default:** _none_

</details>

### Direct Download: Cloudflare Bypass

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `USE_CF_BYPASS` | Attempt to bypass Cloudflare protection on download sites. | boolean | `true` |
| `USING_EXTERNAL_BYPASSER` | Use FlareSolverr or similar external service instead of built-in bypasser. Caution: May have limitations with custom DNS, Tor and proxies. You may experience slower downloads and and poorer reliability compared to the internal bypasser. | boolean | `false` |
| `EXT_BYPASSER_URL` | URL of the external bypasser service (e.g., FlareSolverr). | string | `http://flaresolverr:8191` |
| `EXT_BYPASSER_PATH` | API path for the external bypasser. | string | `/v1` |
| `EXT_BYPASSER_TIMEOUT` | Timeout for external bypasser requests in milliseconds. | number | `60000` |

<details>
<summary>Detailed descriptions</summary>

#### `USE_CF_BYPASS`

**Enable Cloudflare Bypass**

Attempt to bypass Cloudflare protection on download sites.

- **Type:** boolean
- **Default:** `true`
- **Requires restart:** Yes

#### `USING_EXTERNAL_BYPASSER`

**Use External Bypasser**

Use FlareSolverr or similar external service instead of built-in bypasser. Caution: May have limitations with custom DNS, Tor and proxies. You may experience slower downloads and and poorer reliability compared to the internal bypasser.

- **Type:** boolean
- **Default:** `false`
- **Requires restart:** Yes

#### `EXT_BYPASSER_URL`

**External Bypasser URL**

URL of the external bypasser service (e.g., FlareSolverr).

- **Type:** string
- **Default:** `http://flaresolverr:8191`
- **Requires restart:** Yes

#### `EXT_BYPASSER_PATH`

**External Bypasser Path**

API path for the external bypasser.

- **Type:** string
- **Default:** `/v1`
- **Requires restart:** Yes

#### `EXT_BYPASSER_TIMEOUT`

**External Bypasser Timeout (ms)**

Timeout for external bypasser requests in milliseconds.

- **Type:** number
- **Default:** `60000`
- **Requires restart:** Yes
- **Constraints:** min: 10000, max: 300000

</details>

### Direct Download: Mirrors

| Variable | Description | Type | Default |
|----------|-------------|------|---------|
| `AA_BASE_URL` | Select 'Auto' to try mirrors from your list on startup and fall back on failures. Choosing a specific mirror locks Shelfmark to that mirror (no fallback). | string (choice) | `auto` |
| `AA_MIRROR_URLS` | Editable list of AA mirrors. Used to populate the Primary Mirror dropdown and the order used when Auto is selected. Type a URL and press Enter to add. Order matters for auto-rotation | string | `https://annas-archive.gl,https://annas-archive.pk,https://annas-archive.vg,https://annas-archive.gd` |
| `AA_ADDITIONAL_URLS` | Deprecated. Use Mirrors instead. This is kept for backwards compatibility with existing installs and environment variables. | string | _none_ |
| `LIBGEN_ADDITIONAL_URLS` | Comma-separated list of custom LibGen mirrors to add to the defaults. | string | _none_ |
| `ZLIB_PRIMARY_URL` | Z-Library mirror to use for downloads. | string (choice) | `https://z-lib.fm` |
| `ZLIB_ADDITIONAL_URLS` | Comma-separated list of custom Z-Library mirror URLs. | string | _none_ |
| `WELIB_PRIMARY_URL` | Welib mirror to use for downloads. | string (choice) | `https://welib.org` |
| `WELIB_ADDITIONAL_URLS` | Comma-separated list of custom Welib mirror URLs. | string | _none_ |

<details>
<summary>Detailed descriptions</summary>

#### `AA_BASE_URL`

**Primary Mirror**

Select 'Auto' to try mirrors from your list on startup and fall back on failures. Choosing a specific mirror locks Shelfmark to that mirror (no fallback).

- **Type:** string (choice)
- **Default:** `auto`
- **Options:** `auto` (Auto (Recommended)), `https://annas-archive.gl` (annas-archive.gl), `https://annas-archive.pk` (annas-archive.pk), `https://annas-archive.vg` (annas-archive.vg), `https://annas-archive.gd` (annas-archive.gd)

#### `AA_MIRROR_URLS`

**Mirrors**

Editable list of AA mirrors. Used to populate the Primary Mirror dropdown and the order used when Auto is selected. Type a URL and press Enter to add. Order matters for auto-rotation

- **Type:** string
- **Default:** `https://annas-archive.gl,https://annas-archive.pk,https://annas-archive.vg,https://annas-archive.gd`

#### `AA_ADDITIONAL_URLS`

**Additional Mirrors (Legacy)**

Deprecated. Use Mirrors instead. This is kept for backwards compatibility with existing installs and environment variables.

- **Type:** string
- **Default:** _none_

#### `LIBGEN_ADDITIONAL_URLS`

**Additional Mirrors**

Comma-separated list of custom LibGen mirrors to add to the defaults.

- **Type:** string
- **Default:** _none_

#### `ZLIB_PRIMARY_URL`

**Primary Mirror**

Z-Library mirror to use for downloads.

- **Type:** string (choice)
- **Default:** `https://z-lib.fm`
- **Options:** `https://z-lib.fm` (z-lib.fm), `https://z-lib.gs` (z-lib.gs), `https://z-lib.id` (z-lib.id), `https://z-library.sk` (z-library.sk), `https://zlibrary-global.se` (zlibrary-global.se)

#### `ZLIB_ADDITIONAL_URLS`

**Additional Mirrors**

Comma-separated list of custom Z-Library mirror URLs.

- **Type:** string
- **Default:** _none_

#### `WELIB_PRIMARY_URL`

**Primary Mirror**

Welib mirror to use for downloads.

- **Type:** string (choice)
- **Default:** `https://welib.org`
- **Options:** `https://welib.org` (welib.org)

#### `WELIB_ADDITIONAL_URLS`

**Additional Mirrors**

Comma-separated list of custom Welib mirror URLs.

- **Type:** string
- **Default:** _none_

</details>