Settings

Cadmus reads settings from Settings/Settings-*.toml. Settings can be changed via Main Menu → Settings, which opens the built-in settings editor.

Legend:

✏️ Editable in the settings editor
🔑 Required for feature to work
🧪 Only available in test builds
📱 Kobo

General Settings

`keyboard-layout`

✏️

Keyboard layout to use for text input.

Possible values: "English", "Russian".

keyboard-layout = "English"

`sleep-cover`

✏️

Handle the magnetic sleep cover event.

sleep-cover = true

✏️

Automatically enter shared mode when connected to a computer, skipping the “Share storage via USB?” prompt.

Tip

Turn this on if you update Cadmus via USB often — you won’t have to confirm the sharing dialog each time you plug in.

auto-share = false

`auto-suspend`

✏️

Number of minutes of inactivity after which the device will automatically go to sleep.

Zero means never.

auto-suspend = 30.0

`auto-power-off`

✏️

Delay in days after which a suspended device will power off.

Zero means never.

auto-power-off = 3.0

`button-scheme`

✏️

Defines how the back and forward buttons are mapped to page forward and page backward actions.

Possible values: "natural", "inverted".

button-scheme = "natural"

`locale`

✏️

The preferred language for the user interface, using BCP 47 format (e.g., "en-US", "de-DE").

This setting is optional. When not set, en-GB is used.

locale = "en-GB"

Reader

Settings that control the reading experience.

`reader.finished`

✏️

What to do when you finish reading a book.

Possible values:

"notify" (show a notification)
"close" (close the book and go back)
"go-to-next" (open the next book in the library).

[reader]
finished = "close"

Libraries

✏️

Document library configuration. Each library has a name, path, and mode.

[[libraries]]
name = "On Board"
path = "/mnt/onboard"
mode = "database"

`libraries.mode`

✏️

Library indexing mode.

Possible values: "database", "filesystem".

`libraries.finished`

✏️

Override the reader.finished setting for this specific library. When set, this takes precedence over the global reader setting.

Possible values:

"notify"
"close"
"go-to-next".
Leave unset to inherit the global reader.finished setting.

[[libraries]]
name = "KePub"
path = "/mnt/onboard/.kobo/kepub"
finished = "go-to-next"

Intermissions

✏️

Defines the images displayed when entering an intermission state.

[intermissions]
suspend = "logo:"
power-off = "logo:"
share = "logo:"

`intermissions.suspend`

✏️

Image displayed when the device enters sleep mode.

Possible values: "logo:" (built-in logo), "cover:" (current book cover), or a path to a custom image file.

`intermissions.power-off`

✏️

Image displayed when the device powers off.

Possible values: "logo:" (built-in logo), "cover:" (current book cover), or a path to a custom image file.

`intermissions.share`

✏️

Image displayed when entering USB sharing mode.

Possible values: "logo:" (built-in logo), "cover:" (current book cover), or a path to a custom image file.

Import

These settings control how Cadmus imports documents from your device. They are available in the Settings → Import menu.

`import.startup-trigger`

✏️

Automatically import new books when Cadmus starts.

[import]
startup-trigger = true

Tip

If this is turned off, you can still trigger an import manually from the home screen: tap the database icon (bottom-left corner) and choose Import.

`import.sync-metadata`

✏️

Re-extract metadata (title, author, etc.) whenever a document changes.

[import]
sync-metadata = true

`import.metadata-kinds`

File extensions of documents whose metadata is extracted during import.

[import]
metadata-kinds = ["epub", "pdf", "djvu"]

`import.allowed-kinds`

File extensions of documents considered during the import process.

[import]
allowed-kinds = ["djvu", "xps", "fb2", "txt", "pdf", "oxps", "cbz", "epub"]

OTA

The OTA feature downloads builds from GitHub.

Authentication for main branch and PR builds uses GitHub device auth flow. When you select a build that requires authentication, Cadmus will display a short code and a URL. Visit github.com/login/device on any device, enter the code, and Cadmus will automatically continue the download once you authorize.

The token is saved to disk after the first authorization so you will not be prompted again on subsequent downloads.

For step-by-step instructions with screenshots, see the OTA updates guide.

Telemetry

Cadmus writes JSON logs to disk. When the build enables the otel feature, it can also export logs to an OpenTelemetry endpoint.

These settings are available in the Settings → Telemetry menu.

Important

Changes to these settings only take effect after restarting Cadmus. The application initializes telemetry on startup.

`logging`

[logging]
enabled = true
level = "info"
max-files = 3
directory = "logs"
# otlp-endpoint = "https://otel.example.com:4318"

`logging.enabled`

✏️

Enable or disable structured JSON logging.

[logging]
enabled = true

`logging.level`

✏️

Minimum log level to record.

Possible values: "trace", "debug", "info", "warn", "error".

[logging]
level = "info"

`logging.max-files`

Number of log files to keep. Only the most recent N files are kept — older ones are deleted automatically when Cadmus starts.

Default: 3
Set to 0 to keep all log files.

[logging]
max-files = 3

`logging.otlp-endpoint`

✏️ (only when the otel feature is enabled)

Optional OTLP endpoint for exporting logs to an OpenTelemetry collector.

[logging]
otlp-endpoint = "https://otel.example.com:4318"

Environment override:

OTEL_EXPORTER_OTLP_ENDPOINT takes precedence over logging.otlp-endpoint.

`logging.enable-kern-log`

🧪 📱 ✏️

Captures kernel logs via logread -F and forwards them to structured logging with the target cadmus_core::logging:kern.

[logging]
enable-kern-log = false

`logging.enable-dbus-log`