CLI reference

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Every built-in command and option of the bookclerk command-line tool. During development, run it as cargo dev-cli -- <command> or cargo run -p bookclerk-cli -- <command>. bookclerk <command> --help prints the same text in a terminal.

Installed plugins can add their own commands under bookclerk plugins <plugin-id>. Those depend on which plugins are installed, so they are not listed here; bookclerk plugins <plugin-id> --help shows them.

This page is generated from the CLI's own definitions, so do not edit it by hand. After changing a command, run UPDATE_CLI_REFERENCE=1 cargo test -p bookclerk-cli cli_reference and commit the result.

Global options

These options work with every command. Some commands have their own option of the same name: written after the command's name, it means the command's option, and written before it, the global one. These are bookclerk export postgres --format.

  • --bookclerk-files, --bookclerkFiles <BOOKCLERK_FILES>: Bookclerk files directory (BOOKCLERK_FILES_DIR) (environment variable BOOKCLERK_FILES_DIR)
  • --config <CONFIG>: Path to config.toml (default: {bookclerk-files}/config.toml) (environment variable BOOKCLERK_CONFIG)
  • -v, --verbose: Increase tracing verbosity (-v warnings, -vv debug, -vvv trace). Default is quiet: command output only (override with BOOKCLERK_LOG)
  • --format <FORMAT>: Machine-readable output for list/status style commands (one of text, json; default text)

Commands

bookclerk library

Library scan, acquire, search, accounts, and status

bookclerk library [OPTIONS] <COMMAND>

Commands:

bookclerk library accounts

List configured bookstore accounts

bookclerk library accounts [OPTIONS]

Options:

  • --source <SOURCE>: Content source filter. Omit for all
  • -b, --bare: Tab-separated values for scripts (source, account, name, locale, scan, auth)

bookclerk library set-scan

Enable or disable an account for library scans (GUI: Include in library scan)

bookclerk library set-scan [OPTIONS] <ACCOUNT>

Arguments:

  • <ACCOUNT>: Account id, auth-file stem, or nickname

Options:

  • --source <SOURCE>: Content source, when the same account id exists on several plugins
  • --scan <SCAN>: Include this account when scanning (default: true) (one of true, false)

bookclerk library set-pace

Show or set how fast Bookclerk downloads from an account when it starts the downloads itself (auto-acquire, upgrades, requests from other libraries). With no option, prints the account's pace

bookclerk library set-pace [OPTIONS] <ACCOUNT>

Arguments:

  • <ACCOUNT>: Account id, auth-file stem, or nickname

Options:

  • --source <SOURCE>: Content source, when the same account id exists on several plugins
  • --per-day <PER_DAY>: Downloads allowed in any rolling 24 hours (1 to 10000)
  • --gap-seconds <GAP_SECONDS>: Seconds between two downloads (0 to 86400)
  • --unlimited: No daily budget and no gap (a store's cool-down still applies)
  • --default: Go back to the storefront's declared pace
  • --clear-cooldown: End the cool-down the store asked for

bookclerk library status

Show token validity / refresh health across sources

bookclerk library status [OPTIONS]

Options:

  • --source <SOURCE>: Content source filter. Omit for all

bookclerk library revoke-account

Remove store credentials but keep acquired books and account rows

bookclerk library revoke-account [OPTIONS] <ACCOUNT>

Arguments:

  • <ACCOUNT>: Account id, auth-file stem, or nickname

Options:

  • --source <SOURCE>: Content source, when the same account id exists on several plugins

bookclerk library scan

Sync the library from the content sources: queues one scan job per account (every scan-enabled account when none is named) for a bookclerkd node to run, and waits for them

bookclerk library scan [OPTIONS] [ACCOUNT]...

Arguments:

  • [ACCOUNT]...: Account nickname(s) or id(s) to scan

Options:

  • --account <ACCOUNT>: Limit sync to one account (alias for positional account list)
  • --source <SOURCE>: Limit to one content source (audible, libro, graphicaudio, or chirp). Default: all
  • --instance <INSTANCE>: Pin the scan to one deployed plugin instance (default: each plugin's default instance)
  • --match-storage: After scan, match existing files in storage to library rows. Lists .m4b / .mp3 / .m4a / .flac / .aac / .ogg / .oga, probes object metadata (no body download), and falls back to ASIN/ISBN tokens in the path.
  • --fix-layout: With --match-storage, relocate matched audio + sidecars onto the configured naming-profile layout (also library.fix_storage_layout)
  • --no-wait: Queue the scan jobs and print their ids without waiting for a bookclerkd node to run them

bookclerk library acquire

Download + decrypt + store titles: queues one acquire job per title id (or one for every pending title) for a bookclerkd node to run, and waits for them. --dry-run only prints planned keys, here

bookclerk library acquire [OPTIONS] [ID]...

Arguments:

  • [ID]...: Positional title id(s): UUID, ASIN, ISBN, or product id

Options:

  • --asin <ASIN>: Acquire a single ASIN / product id / UUID
  • --isbn <ISBN>: Alias for --asin (Libro ISBN or any title id)
  • --account <ACCOUNT>: Account id (required with --asin when multiple accounts exist)
  • --instance <INSTANCE>: Fetch through this deployed plugin instance (default: the book's plugin default instance)
  • --dry-run: Dry-run: print planned storage keys only
  • -f, --force: Re-download even when matching media already exists in storage
  • -p, --pdf: Download companion PDF only
  • --no-wait: Queue the acquire jobs and print their ids without waiting for a bookclerkd node to run them

bookclerk library upload

Upload files, folders or ZIP / tar archives to a running bookclerkd as one upload, then wait for the ingest job.

Each folder keeps its name and layout; symbolic links are skipped. The books are held by the library's first active Owner. Unidentified books are stored for an Administrator to review.

bookclerk library upload [OPTIONS] <PATH>...

Arguments:

  • <PATH>...: Files, folders and archives to upload

Options:

  • --no-wait: Commit the upload and print its job id without waiting for the ingest job
  • --resume <UPLOAD_ID>: Continue an earlier upload of the same paths that did not finish, from the bytes the daemon already holds

bookclerk library set-status

Match storage files to library rows and update acquire status.

Lists audio in storage and probes custom object metadata (S3 HeadObject / local .bookclerk-meta.json) without downloading bodies. Falls back to ASIN/ISBN tokens embedded in the object key.

bookclerk library set-status [OPTIONS] [ASIN]...

Arguments:

  • [ASIN]...: Title ids to update (UUID, ASIN, ISBN, or product id); empty means all matching the account filter

Options:

  • --account <ACCOUNT>: Limit matching to this account id, stem, or nickname
  • --keep-missing: Do not clear Acquired status when the file is missing
  • --downloaded: Only mark titles with matching files as Acquired
  • --not-downloaded: Only clear Acquired status when the file is missing
  • -f, --force: Force status without checking storage
  • --fix-layout: Relocate matched audio + accompanying sidecars onto the configured naming-profile layout (library.fix_storage_layout)

bookclerk library get-license

Fetch a content license for an ASIN

bookclerk library get-license [OPTIONS] <ASIN>

Arguments:

  • <ASIN>: Title id to resolve to an Audible ASIN (UUID, ASIN, ISBN, or product id)

Options:

  • --account <ACCOUNT>: Audible account when the title is missing or owned on multiple accounts
  • --json: Emit full license summary as JSON
  • --full: Emit full license API response JSON (not summary)

Search the library's works by title, people, series or store id

bookclerk library search [OPTIONS] <QUERY>

Arguments:

  • <QUERY>: Lucene-style query string

Options:

  • -n, --limit <LIMIT>: Max results (0 = all) (default 10)
  • -b, --bare: Print work ids only
  • --rebuild-index: Rebuild the works search index before querying
  • --filter <FILTER>: Run a saved quick filter by name

bookclerk library export

Export library titles as CSV / JSON / XLSX (alias of export library): the whole library, or with --user that person's view

bookclerk library export [OPTIONS] --path <PATH> [ASINS]...

Arguments:

  • [ASINS]...: Limit to specific ASINs

Options:

  • -p, --path <PATH>: Output file path (required)
  • --csv: Write CSV (default when no format flag is set and the path ends in .csv)
  • --json: Write JSON
  • --xlsx: Write XLSX
  • --account <ACCOUNT>: Limit the export to this account id, stem, or nickname
  • --user <USER>: Fill tags and is_finished with this person's own state (login name or user id); without it they are empty

bookclerk library list

List books in the local library DB

bookclerk library list [OPTIONS]

Options:

  • --account <ACCOUNT>: Limit listed rows to this account id, stem, or nickname
  • --status <STATUS>: Filter by acquire status (acquired, not_downloaded, …)

bookclerk library convert

Add another copy of stored books, made from the copy the library holds and kept beside it (queued for the daemon, like acquire)

bookclerk library convert [OPTIONS] <ID>...

Arguments:

  • <ID>...: Title ids (uuid, ASIN, ISBN, product id) of the books to convert

Options:

  • --account <ACCOUNT>: Limit conversion to this account id, stem, or nickname
  • --to <FORMAT:QUALITY>: The copy to add, as output.copies writes it (mp3:64k-mono, m4b:original, opus:32k). Defaults to an MP3 at the library's output.lame quality
  • -f, --force: Make the copy again when the book already has it
  • --no-wait: Queue the jobs and print their ids without waiting

bookclerk library filters

Manage saved quick filters

bookclerk library filters [OPTIONS] <COMMAND>

Commands:

bookclerk library filters list

List saved filters

bookclerk library filters list [OPTIONS]

bookclerk library filters save

Save or update a named filter

bookclerk library filters save [OPTIONS] <NAME> <QUERY>

Arguments:

  • <NAME>: Saved filter name to create or overwrite
  • <QUERY>: Lucene-style query string

bookclerk library filters delete

Delete a saved filter

bookclerk library filters delete [OPTIONS] <NAME>

Arguments:

  • <NAME>: Saved filter name to delete

bookclerk library tags

Read or set a work's library tags, which everyone sees, the Library filters by, and a patron scope can include or exclude

bookclerk library tags [OPTIONS] <COMMAND>

Commands:

bookclerk library tags get

Print a work's library tags, one per line, with where each came from

bookclerk library tags get [OPTIONS] <WORK>

Arguments:

  • <WORK>: The work id (a top-level work, as GET /api/library/works lists it)

bookclerk library tags set

Replace the tags set in Bookclerk on a work; tags read from a sidecar file stay

bookclerk library tags set [OPTIONS] <WORK>

Arguments:

  • <WORK>: The work id

Options:

  • --tag <TAG>: A tag to set (repeatable). With none, the work's tags set in Bookclerk are removed

bookclerk library collections

Read or set the library's collections: named parts of the library, each defined by storage key prefixes, which the Library filters by and a patron scope can include or exclude

bookclerk library collections [OPTIONS] <COMMAND>

Commands:

bookclerk library collections get

Print each collection with its prefixes

bookclerk library collections get [OPTIONS]

bookclerk library collections set

Replace every collection. The page index is rebuilt by a running daemon's next heartbeat

bookclerk library collections set [OPTIONS]

Options:

  • --collection <NAME=PREFIXES>: A collection as NAME=PREFIX[,PREFIX…] (Kids=kids/,children/), repeatable. With none, every collection is removed

bookclerk discover

Recommendations, embeddings, listening sync, and title requests

bookclerk discover [OPTIONS] <COMMAND>

Commands:

bookclerk discover recommend

Optionally enrich + embed works, then print recommendations

bookclerk discover recommend [OPTIONS]

Options:

  • -n, --limit <LIMIT>: Max recommendations to print
  • --no-purchase-hints: Skip purchase-hint HTTP lookups
  • --user <USER>: Filter listening signals to one external user id (any listening integration)
  • --no-listening: Ignore listening_progress entirely (owned-library taste only)
  • --listening-provider <ID>: Only use listening rows from these integration ids (repeatable)

bookclerk discover enrich-metadata

Fill metadata gaps (description, subjects, cover, language) from the deployed metadata-provider plugins, such as Open Library

bookclerk discover enrich-metadata [OPTIONS]

bookclerk discover embed

Embed dirty works with the built-in word-hash vectors

bookclerk discover embed [OPTIONS]

bookclerk discover sync-listening

Sync listening progress from all capable integrations into the library DB

bookclerk discover sync-listening [OPTIONS]

bookclerk discover wishlist

Personal wishlist helpers (also feed the shared global queue)

bookclerk discover wishlist [OPTIONS] <COMMAND>

Commands:

bookclerk discover wishlist add

Add an open wishlist item

bookclerk discover wishlist add [OPTIONS] <TITLE>

Arguments:

  • <TITLE>: Display title for the wishlist row (required positional)

Options:

  • --authors <AUTHORS>: Optional author list stored on the request
  • --asin <ASIN>: Optional Audible ASIN used for identity matching
  • --isbn <ISBN>: Optional ISBN-13 used for identity matching
  • --notes <NOTES>: Optional operator notes stored on the request

bookclerk discover wishlist list

List open wishlist items (operator-owned when no portal identity)

bookclerk discover wishlist list [OPTIONS]

bookclerk discover wishlist remove

Un-wishlist by uuid (sets status to cancelled)

bookclerk discover wishlist remove [OPTIONS] <UUID>

Arguments:

  • <UUID>: Wishlist entry UUID to cancel

bookclerk integrations

Outbound integrations (Audiobookshelf) and claim tickets

bookclerk integrations [OPTIONS] <COMMAND>

Commands:

bookclerk integrations status

Show health of configured integrations

bookclerk integrations status [OPTIONS]

bookclerk integrations test

Probe connectivity for one (or all) enabled integrations

bookclerk integrations test [OPTIONS]

Options:

  • --integration <INTEGRATION>: Integration id (default: all enabled)

bookclerk integrations tickets

Claim ticket management

bookclerk integrations tickets [OPTIONS] <COMMAND>

Commands:

bookclerk integrations tickets create

Mint a claim ticket for an external identity

bookclerk integrations tickets create [OPTIONS] --external-user-id <EXTERNAL_USER_ID>

Options:

  • --provider <PROVIDER>: Integration provider id (audiobookshelf) (default audiobookshelf)
  • --external-user-id <EXTERNAL_USER_ID>: External user id from the provider (required)
  • --label <LABEL>: Optional display label

bookclerk integrations tickets list

List open (unredeemed, unexpired) claim tickets

bookclerk integrations tickets list [OPTIONS]

bookclerk integrations scan

Trigger a remote library scan on an integration that supports it

bookclerk integrations scan [OPTIONS] --integration <INTEGRATION>

Options:

  • --integration <INTEGRATION>: Integration id (audiobookshelf, …) (required)
  • --force: Force full rescan when the integration supports it

bookclerk plugins

Dynamically discovered third-party plugins

bookclerk plugins [OPTIONS] <COMMAND>

Commands:

  • bookclerk plugins list: List plugins found under plugin search directories
  • bookclerk plugins search: Search configured registries (and crates.io) for Bookclerk plugins
  • bookclerk plugins install: Install a plugin version into the library from a source-qualified coordinate or a local archive. The first installed version (or --activate) becomes the active version every node runs; deploy it with plugins deploy
  • bookclerk plugins update: Install and activate a newer version of an installed plugin (or update a staged package by its receipt)
  • bookclerk plugins rollback: Activate an earlier installed version of a plugin
  • bookclerk plugins versions: List installed versions (the active one is starred)
  • bookclerk plugins uninstall: Uninstall a plugin: clear its active version and undeploy it from every node (or remove a staged package directory)
  • bookclerk plugins info: Show details for one discovered plugin (local + receipt)
  • bookclerk plugins diagnose: Run diagnose probes for one (or all) plugins that support it
  • bookclerk plugins doctor: Check install integrity, target, jail, and describe/health status
  • bookclerk plugins deploy: Deploy a plugin instance. With no flags it runs on this node (or on --node) by hand: the instance's deployment there is present. With --replicas the library scheduler (one daemon, under a library lease) places it on that many nodes carrying every --on label and writes the deployments itself; --manual hands those deployments back to be managed by hand
  • bookclerk plugins undeploy: Undeploy a plugin instance from this node (or --node): its deployment there becomes absent and the guest is retired
  • bookclerk plugins instances: Plugin instances: one per plugin by default, more when an operator wants several configurations of one plugin
  • bookclerk plugins config: Instance settings, validated against the plugin's declared schema
  • bookclerk plugins approve: Approve network domains and host bindings for a plugin
  • bookclerk plugins registry: Manage configured plugin registries
  • bookclerk plugins db: Manage isolated plugin database bindings (capabilities.bindings.databases)

bookclerk plugins list

List plugins found under plugin search directories

bookclerk plugins list [OPTIONS]

Search configured registries (and crates.io) for Bookclerk plugins

bookclerk plugins search [OPTIONS] [QUERY]

Arguments:

  • [QUERY]: Free-text query

Options:

  • --limit <LIMIT>: Max hits to fetch (1–100) (default 25)

bookclerk plugins install

Install a plugin version into the library from a source-qualified coordinate or a local archive. The first installed version (or --activate) becomes the active version every node runs; deploy it with plugins deploy

bookclerk plugins install [OPTIONS] <COORDINATE>

Arguments:

  • <COORDINATE>: Coordinate (cargo:…@ver, registry:…#name@ver, local:…) or legacy crate name

Options:

  • --archive <ARCHIVE>: Local archive path (sets artifact to this file; use with a static manifest coord)
  • --manifest <MANIFEST>: Path to a Bookclerk package manifest JSON (required with --archive alone)
  • --target <TARGET>: Override Bookclerk target (e.g. linux-x64-gnu)
  • --activate: Make this the active version even when another version is active
  • --approve-capabilities: Record the requested consent as approved (no separate approve)
  • --allow-unverified-publisher: Allow community packages without independent publisher authenticity (digest still required)
  • --dry-run: Do not download; only resolve and print the plan
  • --offline: Refuse remote downloads

bookclerk plugins update

Install and activate a newer version of an installed plugin (or update a staged package by its receipt)

bookclerk plugins update [OPTIONS] [ID]

Arguments:

  • [ID]: Plugin runtime id (default: all with receipts)

Options:

  • --to <TO>: Exact version to install
  • --allow-unverified-publisher: Allow community packages without independent publisher authenticity on this update (digest still required)
  • --approve-capabilities: Approve sandbox/network capability changes without a separate prompt
  • --dry-run: Resolve and print the plan without downloading

bookclerk plugins rollback

Activate an earlier installed version of a plugin

bookclerk plugins rollback [OPTIONS] <ID> <VERSION>

Arguments:

  • <ID>: Plugin alias or PluginKey
  • <VERSION>: Installed version to activate

bookclerk plugins versions

List installed versions (the active one is starred)

bookclerk plugins versions [OPTIONS] [ID]

Arguments:

  • [ID]: Only this plugin (alias or PluginKey)

bookclerk plugins uninstall

Uninstall a plugin: clear its active version and undeploy it from every node (or remove a staged package directory)

bookclerk plugins uninstall [OPTIONS] <ID>

Arguments:

  • <ID>: Plugin runtime id

Options:

  • --purge-state: Also delete $FILES_DIR/plugin-state/<PluginKey>/
  • --discard-acl-journals: Delete rejected ACL journals with plugin state. Requires --purge-state. Does not revoke the package-SID ACEs those records name; read the rejected file and remove those ACEs by hand first

bookclerk plugins info

Show details for one discovered plugin (local + receipt)

bookclerk plugins info [OPTIONS] <ID>

Arguments:

  • <ID>: Plugin id

bookclerk plugins diagnose

Run diagnose probes for one (or all) plugins that support it

bookclerk plugins diagnose [OPTIONS] [ID]

Arguments:

  • [ID]: Plugin id (default: all discovered that are enabled)

bookclerk plugins doctor

Check install integrity, target, jail, and describe/health status

bookclerk plugins doctor [OPTIONS] [ID]

Arguments:

  • [ID]: Plugin id (default: all discovered)

bookclerk plugins deploy

Deploy a plugin instance. With no flags it runs on this node (or on --node) by hand: the instance's deployment there is present. With --replicas the library scheduler (one daemon, under a library lease) places it on that many nodes carrying every --on label and writes the deployments itself; --manual hands those deployments back to be managed by hand.

Database adapters are the bootstrap exception and still select [database].plugin in config.toml.

bookclerk plugins deploy [OPTIONS] <ID>

Arguments:

  • <ID>: Plugin alias, PluginKey, or plugin instance id (an alias or key names the plugin's default instance)

Options:

  • --node <NODE>: Node to deploy on by hand (default: this node)
  • --replicas <REPLICAS>: Nodes that should run the instance: a number (0 stops every replica) or all (every live, schedulable node with room)
  • --on <LABEL>: Label constraint every chosen node must satisfy (nas, zone=eu, node=<id>, target=linux-x64-gnu); prefix with ! to exclude. Repeatable
  • --manual: Drop the scheduler placement: the instance's deployments stay as they are and are managed by hand again

bookclerk plugins undeploy

Undeploy a plugin instance from this node (or --node): its deployment there becomes absent and the guest is retired

bookclerk plugins undeploy [OPTIONS] <ID>

Arguments:

  • <ID>: Plugin alias, PluginKey, or plugin instance id

Options:

  • --node <NODE>: Node to undeploy from (default: this node)

bookclerk plugins instances

Plugin instances: one per plugin by default, more when an operator wants several configurations of one plugin

bookclerk plugins instances [OPTIONS] <COMMAND>

Commands:

bookclerk plugins instances list

List instances with their deployments on every node

bookclerk plugins instances list [OPTIONS]

Options:

  • --plugin <PLUGIN>: Only instances of this plugin (alias or PluginKey)

bookclerk plugins instances create

Create another instance of a plugin that has a pinned schema

bookclerk plugins instances create [OPTIONS] <PLUGIN>

Arguments:

  • <PLUGIN>: Plugin alias or PluginKey

Options:

  • --name <NAME>: Operator-facing name
  • --node <NODE_ID>: Make the instance local to this node (a node's own local output, for example): it deploys only there and is never placed by the scheduler

bookclerk plugins instances delete

Delete an instance that has no deployment on any node

bookclerk plugins instances delete [OPTIONS] <INSTANCE>

Arguments:

  • <INSTANCE>: Plugin instance id

bookclerk plugins instances filter

Show or change which books a storage destination takes

bookclerk plugins instances filter [OPTIONS] <COMMAND>

Commands:

  • bookclerk plugins instances filter get: Show a destination's filter
  • bookclerk plugins instances filter set: Replace a destination's filter. Each rule is FIELD=VALUE, where FIELD is patron (a user id), storefront (a plugin alias such as audible), account (a store account id), media_kind (book or podcast), format (a copy format: m4b, mp3, mp3_chapters or original) or quality (a copy quality such as original, 64k-mono or v2). With any --include, the destination takes only books that match one; an --exclude always wins. format and quality rules choose which of the library's copies (output.copies) the destination receives, the same way among themselves. Acquires that start afterwards use the new filter
  • bookclerk plugins instances filter clear: Remove a destination's filter so it takes every book
bookclerk plugins instances filter get

Show a destination's filter

bookclerk plugins instances filter get [OPTIONS] <INSTANCE>

Arguments:

  • <INSTANCE>: Plugin alias, PluginKey, or plugin instance id of the destination
bookclerk plugins instances filter set

Replace a destination's filter. Each rule is FIELD=VALUE, where FIELD is patron (a user id), storefront (a plugin alias such as audible), account (a store account id), media_kind (book or podcast), format (a copy format: m4b, mp3, mp3_chapters or original) or quality (a copy quality such as original, 64k-mono or v2). With any --include, the destination takes only books that match one; an --exclude always wins. format and quality rules choose which of the library's copies (output.copies) the destination receives, the same way among themselves. Acquires that start afterwards use the new filter

bookclerk plugins instances filter set [OPTIONS] <INSTANCE>

Arguments:

  • <INSTANCE>: Plugin alias, PluginKey, or plugin instance id of the destination

Options:

  • --include <FIELD=VALUE>: Take books that match this rule (repeatable)
  • --exclude <FIELD=VALUE>: Refuse books that match this rule (repeatable)
bookclerk plugins instances filter clear

Remove a destination's filter so it takes every book

bookclerk plugins instances filter clear [OPTIONS] <INSTANCE>

Arguments:

  • <INSTANCE>: Plugin alias, PluginKey, or plugin instance id of the destination

bookclerk plugins instances intake

Show or change whether a storage instance is a drop folder: a folder Bookclerk watches and adds whatever lands there to the library

bookclerk plugins instances intake [OPTIONS] <COMMAND>

Commands:

bookclerk plugins instances intake get

Show whether a storage instance is a drop folder, and its settings

bookclerk plugins instances intake get [OPTIONS] <INSTANCE>

Arguments:

  • <INSTANCE>: Plugin alias, PluginKey, or plugin instance id of the storage instance
bookclerk plugins instances intake set

Make a storage instance a drop folder, or change a drop folder's settings. Options left out keep their current value (or the default, for a new drop folder). Turning a destination into a drop folder needs the instance undeployed on every node

bookclerk plugins instances intake set [OPTIONS] <INSTANCE>

Arguments:

  • <INSTANCE>: Plugin alias, PluginKey, or plugin instance id of the storage instance

Options:

  • --patron <USER_ID>: User id of the patron who holds every book the folder adds
  • --subfolder: Each top-level folder is named after a patron's username and holds that patron's books
  • --settle-seconds <SECONDS>: Seconds an item must stay unchanged before it is added (5 to 86400; default 60)
  • --scan-interval-seconds <SECONDS>: Seconds between two full listings of the folder (30 to 86400; default 300)
  • --after-ingest <ACTION>: What happens to an item once it is added: move (to _imported/, the default), delete or leave
  • --ignore <PATTERN>: Extra file name pattern to ignore, with * and ? (repeatable; replaces the current list)
  • --clear-ignore: Remove every extra ignore pattern (the built-in list still applies)
  • --prune-imported-days <DAYS>: With --after-ingest move, delete _imported day folders older than this many days (1 to 3650)
  • --no-prune: Keep _imported day folders: turn pruning off
bookclerk plugins instances intake clear

Make a drop folder a destination again. Needs the instance undeployed on every node

bookclerk plugins instances intake clear [OPTIONS] <INSTANCE>

Arguments:

  • <INSTANCE>: Plugin alias, PluginKey, or plugin instance id of the storage instance

bookclerk plugins config

Instance settings, validated against the plugin's declared schema

bookclerk plugins config [OPTIONS] <COMMAND>

Commands:

bookclerk plugins config get

Show an instance's effective settings: schema defaults under the operator's document. Secrets show as set or unset, never their value

bookclerk plugins config get [OPTIONS] <INSTANCE>

Arguments:

  • <INSTANCE>: Plugin alias, PluginKey, or plugin instance id

bookclerk plugins config set

Set one setting. A secret setting takes --secret and reads the value from stdin so it never appears on a command line

bookclerk plugins config set [OPTIONS] <INSTANCE> <KEY> [VALUE]

Arguments:

  • <INSTANCE>: Plugin alias, PluginKey, or plugin instance id
  • <KEY>: Setting key from the plugin's [[settings]]
  • [VALUE]: Value text: true/false, a number, or a string. A table setting takes a JSON array of row objects, or one row with its cells in column order separated by | (an empty cell takes the column default; \| is a literal bar)

Options:

  • --secret: Seal a secret read from stdin
  • --append: For a table setting, add the given rows after the current ones instead of replacing them

bookclerk plugins config unset

Unset one setting so the schema default applies, or drop a secret

bookclerk plugins config unset [OPTIONS] <INSTANCE> <KEY>

Arguments:

  • <INSTANCE>: Plugin alias, PluginKey, or plugin instance id
  • <KEY>: Setting key

Options:

  • --row <N>: For a table setting, remove only this row (counted from 1, as config get lists them) and keep the others

bookclerk plugins approve

Approve network domains and host bindings for a plugin.

Grants cover the plugin's declared outbound domains and bindings. Operators may add extra network destinations. Structural capabilities cannot be invented beyond the package. Redirect policy is separate.

bookclerk plugins approve [OPTIONS] <ID>

Arguments:

  • <ID>: Plugin id

Options:

  • -y, --yes: Approve without interactive confirmation (required when stdin is not a TTY)
  • --reset: Approve the package's request as is, dropping the network destinations you added or denied earlier and your redirect answer. Without it a re-approval keeps them. (An installed version always records its package's request.)

bookclerk plugins registry

Manage configured plugin registries

bookclerk plugins registry [OPTIONS] <COMMAND>

Commands:

bookclerk plugins registry list

List configured registries

bookclerk plugins registry list [OPTIONS]

bookclerk plugins registry add

Add a registry source to config.toml

bookclerk plugins registry add [OPTIONS] <KIND>

Arguments:

  • <KIND>: Adapter kind (one of static, cargo, npm, pypi)

Options:

  • --url <URL>: Index / registry URL (required for static)
  • --name <NAME>: Optional display name

bookclerk plugins registry remove

Remove a registry by index (from registry list) or URL

bookclerk plugins registry remove [OPTIONS]

Options:

  • --index <INDEX>: Zero-based index from plugins registry list
  • --url <URL>: Match by URL

bookclerk plugins db

Manage isolated plugin database bindings (capabilities.bindings.databases)

bookclerk plugins db [OPTIONS] <COMMAND>

Commands:

bookclerk plugins db list

List provisioned plugin database bindings

bookclerk plugins db list [OPTIONS] [PLUGIN]

Arguments:

  • [PLUGIN]: Limit to one plugin id

bookclerk plugins db drop

Drop provisioned binding units and their registry rows.

Physically deletes the SQLite file (and journal sidecars), drops the PostgreSQL database, or deletes the Cloudflare D1 database, then removes the registry row. Physical delete must succeed first; unknown adapters fail closed and keep the row.

bookclerk plugins db drop [OPTIONS] <PLUGIN> [BINDING]

Arguments:

  • <PLUGIN>: Plugin id
  • [BINDING]: Binding name (default: every binding of the plugin)

Options:

  • -y, --yes: Drop without interactive confirmation

bookclerk config

Read or write configuration values

bookclerk config [OPTIONS] <COMMAND>

Commands:

bookclerk config get

Print a configuration value by dotted key or classic Settings.json name

bookclerk config get [OPTIONS] [KEY]

Arguments:

  • [KEY]: Dotted key (output.widevine) or classic name (UseWidevine). Plugin settings are read with bookclerk plugins config get

Options:

  • -b, --bare: Bare list of all classic setting keys and values

bookclerk config set

Set a configuration value and write config.toml

bookclerk config set [OPTIONS] <KEY> <VALUE>

Arguments:

  • <KEY>: Dotted key (library.auto_acquire) or classic name (AutoDownloadEpisodes)
  • <VALUE>: Value to assign

bookclerk config show

Print the effective configuration as TOML-ish summary

bookclerk config show [OPTIONS]

bookclerk config paths

Print resolved filesystem paths

bookclerk config paths [OPTIONS]

bookclerk config master-key

Inspect, wrap, move, export or import the library's data-encryption key

bookclerk config master-key [OPTIONS] <COMMAND>

Commands:

bookclerk config master-key status

Show where the key is kept (the file, the OS keychain or systemd-creds) and whether it is raw (BCK1) or wrapped (BCK2)

bookclerk config master-key status [OPTIONS]

bookclerk config master-key wrap

Wrap a BCK1 key with a passphrase (no-op unlock if already BCK2), in master.key or in its OS keychain item.

Password from BOOKCLERK_AUTH_PASSWORD or [auth].password — never argv.

bookclerk config master-key wrap [OPTIONS]

bookclerk config master-key move

Move the key to the OS keychain, into a systemd-creds credential, or back into master.key, and record the choice as [auth].key_store in config.toml.

The key itself doesn't change, so every sealed secret stays readable. Stop bookclerkd first.

bookclerk config master-key move [OPTIONS] <TO>

Arguments:

  • <TO>: Where to keep the key: keychain, systemd-creds or file

bookclerk config master-key export

Write a recovery copy of the key, wrapped with a password read from stdin (never argv).

Keep it apart from the server's files: with it and its password, the library's sealed secrets can be read.

bookclerk config master-key export [OPTIONS] --out <OUT>

Options:

  • --out <OUT>: File to write (created with mode 0600; never overwritten) (required)

bookclerk config master-key credential

Write the key's envelope, exactly as stored (BCK1, or BCK2 under the auth password), to stdout for systemd-creds encrypt.

For administrators who seal the key into a unit credential themselves (systemd older than 256, or a system credential store): pipe it into systemd-creds encrypt --name=bookclerk-master-key - <file>, load that file with LoadCredentialEncrypted= in the unit, and set [auth].key_store = "systemd-creds". The next start adopts the credential. Refuses to write to a terminal.

bookclerk config master-key credential [OPTIONS]

bookclerk config master-key import

Restore the key from a recovery copy (or a copied master.key) on an install that has no master.key. A wrapped copy's password is read from stdin

bookclerk config master-key import [OPTIONS] --from <FROM>

Options:

  • --from <FROM>: The recovery copy to read (required)

bookclerk config template

Naming template helpers

bookclerk config template [OPTIONS] <COMMAND>

Commands:

bookclerk config template tags

List supported naming template property tags

bookclerk config template tags [OPTIONS]

bookclerk config template profiles

List built-in naming profiles and their templates

bookclerk config template profiles [OPTIONS]

bookclerk config template preview

Preview folder/file templates for a library title

bookclerk config template preview [OPTIONS] <ASIN>

Arguments:

  • <ASIN>: Title ASIN from the local library DB

Options:

  • --account <ACCOUNT>: Account id when the ASIN exists on multiple accounts
  • --profile <PROFILE>: Override output.naming_profile for this preview
  • --folder <FOLDER>: Override output.folder_template for this preview
  • --file <FILE>: Override output.file_template for this preview
  • --ext <EXT>: File extension (default: m4b)

bookclerk config database

Database backend helpers (plugin switch / migration)

bookclerk config database [OPTIONS] <COMMAND>

Commands:

bookclerk config database migrate

Copy library data from one [database].plugin backend to another.

Does not change config.toml unless --apply is passed after a successful copy.

bookclerk config database migrate [OPTIONS] --to <TO>

Options:

  • --from <FROM>: Source plugin id (sqlite, d1, postgres). Default: current [database].plugin
  • --to <TO>: Destination plugin id (required)
  • --dry-run: Report row counts only; do not write to the destination
  • --force: Allow copying into a destination that already has library rows
  • --apply: After a successful migrate, set [database].plugin to --to and write config.toml

bookclerk export

Export library data, backups, or Libation-compatible files

bookclerk export [OPTIONS] <COMMAND>

Commands:

bookclerk export native

Write a portable Bookclerk .tar.gz backup of the files directory

bookclerk export native [OPTIONS] --path <PATH>

Options:

  • -p, --path <PATH>: Destination archive path (required)
  • --include-plugin-manifests: Include plugins/**/plugin.toml (not binaries)
  • --include-cache: Include cache/ (large)
  • --include-logs: Include logs/
  • --include-plugin-databases: Include plugin-databases/ (SQLite binding files)

bookclerk export libation

Export Settings.json, AccountsSettings.json, and LibationContext.db

bookclerk export libation [OPTIONS] --path <PATH>

Options:

  • -p, --path <PATH>: Destination classic Libation Files directory (required)
  • --force: Overwrite an existing destination directory
  • --dry-run: Report only; do not write
  • --user <USER>: Write this person's tags, ratings and finished flags (login name or user id); without it they are empty

bookclerk export library

Export library titles as CSV / JSON / XLSX: the whole library, or with --user that person's view with their tags and finished flags

bookclerk export library [OPTIONS] --path <PATH> [ASINS]...

Arguments:

  • [ASINS]...: Limit to specific ASINs / title ids

Options:

  • -p, --path <PATH>: Output file path (required)
  • --csv: Force CSV even when the destination extension is not .csv
  • --json: Force JSON even when the destination extension is not .json
  • --xlsx: Force XLSX even when the destination extension is not .xlsx
  • --account <ACCOUNT>: Limit exported library rows to this account id when set
  • --user <USER>: Fill tags and is_finished with this person's own state (login name or user id); without it they are empty

bookclerk export postgres

Copy library.db to PostgreSQL

bookclerk export postgres [OPTIONS] --connection <CONNECTION>

Options:

  • -c, --connection <CONNECTION>: PostgreSQL connection string (required)
  • --source <SOURCE>: Source SQLite path (default: {files_dir}/library.db)
  • --format <FORMAT>: Output schema format (one of classic, flat; default classic)

bookclerk import

Import native backups or classic Libation Files

bookclerk import [OPTIONS] <COMMAND>

Commands:

bookclerk import native

Restore a native Bookclerk .tar.gz backup into the files directory

bookclerk import native [OPTIONS] --from <ARCHIVE>

Options:

  • --from <ARCHIVE>: Archive path (required)
  • --force: Overwrite existing files
  • --dry-run: Report only; do not write

bookclerk import libation

Import classic Libation Files (Settings / accounts / DB)

bookclerk import libation [OPTIONS] --from <FROM>

Options:

  • --from <FROM>: Classic Libation Files directory (or BOOKCLERK_CLASSIC_FILES) (required; environment variable BOOKCLERK_CLASSIC_FILES)
  • --force: Overwrite existing config.toml
  • --skip-auth: No-op retained for compatibility (credentials are never imported by migrate)
  • --dry-run: Print what would be imported without writing

bookclerk db

Host schema version, backups, and explicit migrate

bookclerk db [OPTIONS] <COMMAND>

Commands:

bookclerk db version

Show this binary's frozen plan and the database's explicit schema state

bookclerk db version [OPTIONS]

bookclerk db backup

Canonical Bookclerk backup (logically full recovery points)

bookclerk db backup [OPTIONS] <COMMAND>

Commands:

bookclerk db backup create

Write a manual recovery point under files_dir/backups/

bookclerk db backup create [OPTIONS]

Options:

  • --path <PATH>: Optional .tar.gz destination for this recovery point
  • --include-plugin-databases: Capture plugin-owned database bindings in portable Bookclerk SQL. Plugin schema migration remains plugin-owned. Each database unit is replaced completely; a multi-database bundle is not one transaction.

bookclerk db backup list

List recovery points oldest-first

bookclerk db backup list [OPTIONS]

bookclerk db backup verify

Verify a recovery point (objects, schema, typed rows) without restoring

bookclerk db backup verify [OPTIONS] --from <FROM>

Options:

  • --from <FROM>: Recovery-point id, archive, or created_at prefix (required)

bookclerk db backup prune

Prune automatic pre-migrate recovery points and unreferenced objects.

Manual backups are never removed.

bookclerk db backup prune [OPTIONS]

bookclerk db restore

Restore schema and data from a recovery-point id, archive, or timestamp

bookclerk db restore [OPTIONS] --from <FROM>

Options:

  • --from <FROM>: Recovery-point id, .tar.gz archive, or created_at prefix. Restores onto the currently configured database adapter (not necessarily the adapter that captured the backup). (required)

bookclerk db migrate

Apply frozen ups or reversible downs to reach --to

bookclerk db migrate [OPTIONS]

Options:

  • --to <TO>: Target frozen schema version (defaults to this binary's SCHEMA_VERSION)
  • --include-plugin-databases: Include plugin-owned database bindings in the pre-migrate backup

bookclerk daemon

Talk to a running bookclerkd control plane

bookclerk daemon [OPTIONS] <COMMAND>

Commands:

bookclerk daemon health

GET /health

bookclerk daemon health [OPTIONS]

bookclerk daemon status

GET /status (or /api/status)

bookclerk daemon status [OPTIONS]

bookclerk daemon scan

POST /scan (or /api/library/scan)

bookclerk daemon scan [OPTIONS]

Options:

  • --account <ACCOUNT>: Optional account id forwarded in the scan JSON body

bookclerk daemon acquire

POST /acquire (or /api/library/acquire)

bookclerk daemon acquire [OPTIONS]

Options:

  • --asin <ASIN>: Optional product id (ASIN/ISBN) forwarded in the acquire JSON body
  • --account <ACCOUNT>: Optional account id forwarded in the acquire JSON body

bookclerk daemon jobs

GET /jobs (or /api/jobs)

bookclerk daemon jobs [OPTIONS]

bookclerk daemon token

Show or rotate the operator API token (DB-backed; env override wins)

bookclerk daemon token [OPTIONS] [COMMAND]

Commands:

bookclerk daemon token show

Print the current effective operator token (default)

bookclerk daemon token show [OPTIONS]

bookclerk daemon token rotate

Mint a new token, store it in encrypted_secrets, and reload the daemon when reachable

bookclerk daemon token rotate [OPTIONS]

bookclerk events

Durable domain-event outbox and deliveries

bookclerk events [OPTIONS] <COMMAND>

Commands:

bookclerk events list

GET /api/events — recent outbox envelopes

bookclerk events list [OPTIONS]

bookclerk events dead-letters

GET /api/events/deliveries?state=dead_letter

bookclerk events dead-letters [OPTIONS]

bookclerk events retry

POST /api/events/deliveries/{id}/retry

bookclerk events retry [OPTIONS] <ID>

Arguments:

  • <ID>: Delivery id ({event_id}:{plugin_id})

bookclerk events ack

POST /api/events/deliveries/{id}/acknowledge

bookclerk events ack [OPTIONS] <ID>

Arguments:

  • <ID>: Delivery id ({event_id}:{plugin_id})

bookclerk events cancel

POST /api/events/deliveries/{id}/cancel

bookclerk events cancel [OPTIONS] <ID>

Arguments:

  • <ID>: Delivery id ({event_id}:{plugin_id})

bookclerk events resume

POST /api/events/deliveries/{id}/resume

bookclerk events resume [OPTIONS] <ID>

Arguments:

  • <ID>: Delivery id ({event_id}:{plugin_id})

bookclerk libraries

Owner libraries this install hosts for, and consent to their plugins

bookclerk libraries [OPTIONS] <COMMAND>

Commands:

  • bookclerk libraries list: The libraries this install is enrolled in as a host
  • bookclerk libraries join: Enroll this install as a host (a branch) of an owner library
  • bookclerk libraries leave: Leave a library: the owner is told (and revokes this node when it hears), the link stops being dialed and its node keys are deleted
  • bookclerk libraries consents: What each library asks to run here, and whether it may
  • bookclerk libraries approve: Approve an owner plugin's request to run here, optionally narrowed. Name the request you reviewed by the digest libraries consents shows (it covers the version, the grant, the archive URL, the archive digest and the payload digest); it is refused when the library has changed the request since. Only what the request asks for can be approved; a later version that asks for more needs approval again
  • bookclerk libraries scan: Ask a library to scan its library for this node's owner
  • bookclerk libraries revoke: Withdraw an approval: held jobs of the plugin are cancelled and given back, and nothing of it is claimed until this host's operator approves it again (a platform plugin is not approved automatically)

bookclerk libraries list

The libraries this install is enrolled in as a host

bookclerk libraries list [OPTIONS]

bookclerk libraries join

Enroll this install as a host (a branch) of an owner library.

With --url, prints a sign-in link (and opens a browser when it can): a user of that library signs in and approves, and the answer comes back to a loopback listener this command opens. Without it, reads a branch invite (https://<owner>/enroll#bcn1...) from stdin, or prompts for it; an invite is never taken from the command line.

bookclerk libraries join [OPTIONS]

Options:

  • --url <URL>: The owner library's address (https://library.example)
  • --name <NAME>: The name the owner sees for this branch (default: host name)
  • --fingerprint <FINGERPRINT>: The library's certificate fingerprint as Settings → Branches shows it (a sha256: prefix is accepted), confirming a self-signed library without a prompt
  • --as <JOIN_AS>: How to join: branch (default; keeps this install's own database) or shared_branch (shares the library's database and key; only an empty install, and only when an Owner of the library chooses it after a fresh second factor) (one of branch, shared-branch)

bookclerk libraries leave

Leave a library: the owner is told (and revokes this node when it hears), the link stops being dialed and its node keys are deleted

bookclerk libraries leave [OPTIONS]

Options:

  • --library <LIBRARY>: Library id (default: the only enrolled library)

bookclerk libraries consents

What each library asks to run here, and whether it may

bookclerk libraries consents [OPTIONS]

Options:

  • --library <LIBRARY>: Only this library

bookclerk libraries approve

Approve an owner plugin's request to run here, optionally narrowed. Name the request you reviewed by the digest libraries consents shows (it covers the version, the grant, the archive URL, the archive digest and the payload digest); it is refused when the library has changed the request since. Only what the request asks for can be approved; a later version that asks for more needs approval again

bookclerk libraries approve [OPTIONS] --request <DIGEST> <PLUGIN>

Arguments:

  • <PLUGIN>: Canonical plugin key

Options:

  • --library <LIBRARY>: Library id (default: the only enrolled library)
  • --request <DIGEST>: The request_digest of the request you reviewed, from libraries consents (refused when the library now asks for anything else) (required)
  • --deny-domain <DOMAIN>: Take a domain out of the request. Repeatable
  • --deny-binding <BINDING>: Take a binding out of the request (secrets, kv, ...). Repeatable
  • --deny-own-user-agent <HOST>: Refuse the plugin's own User-Agent on a host it asks for; its requests there carry Bookclerk's agent. Repeatable
  • --deny-network: Deny all network access

bookclerk libraries scan

Ask a library to scan its library for this node's owner.

Goes through this install's running daemon, over its link to the owner. The owner plans it as that user: an Owner or Administrator scanning every account gets one job per account, spread over the library's nodes and hosts; anyone else scans only their own accounts. Waits for the jobs unless --no-wait.

bookclerk libraries scan [OPTIONS]

Options:

  • --library <LIBRARY>: Library id (default: the only enrolled library)
  • --account <ACCOUNT>: Scan only this store account of the library
  • --instance <INSTANCE>: Pin the scan to one owner plugin instance
  • --no-wait: Print the queued job ids without waiting for them

bookclerk libraries revoke

Withdraw an approval: held jobs of the plugin are cancelled and given back, and nothing of it is claimed until this host's operator approves it again (a platform plugin is not approved automatically)

bookclerk libraries revoke [OPTIONS] <PLUGIN>

Arguments:

  • <PLUGIN>: Canonical plugin key

Options:

  • --library <LIBRARY>: Library id (default: the only enrolled library)

bookclerk ingress

The library's public address from an ingress plugin

bookclerk ingress [OPTIONS] <COMMAND>

Commands:

bookclerk ingress status

Show the active ingress, what it exposes and the public origin

bookclerk ingress status [OPTIONS]

bookclerk ingress activate

Make a plugin instance the library's active ingress. Needs an Owner account and operator auth on

bookclerk ingress activate [OPTIONS] <PLUGIN>

Arguments:

  • <PLUGIN>: A plugin instance UUID, or a plugin key for its default instance

bookclerk ingress deactivate

Turn ingress off. The adopted origin is kept for next time

bookclerk ingress deactivate [OPTIONS]

bookclerk ingress exposure

Choose what public traffic may reach

bookclerk ingress exposure [OPTIONS] <EXPOSURE>

Arguments:

  • <EXPOSURE>: branches (the default) or library (one of branches, library)

bookclerk ingress accept-origin

Adopt the new origin the active ingress reported. Passkeys and sign-in redirects registered under the old name stop working

bookclerk ingress accept-origin [OPTIONS]

bookclerk nodes

Library nodes: liveness, capacity, budgets, and placement labels

bookclerk nodes [OPTIONS] <COMMAND>

Commands:

  • bookclerk nodes list: Every registered node: liveness, artifact target, and labels
  • bookclerk nodes set: Set a node's scheduling budget or drain it. Applies at that node's next heartbeat
  • bookclerk nodes label: Add or remove placement labels on a node (nas, zone=eu)
  • bookclerk nodes owner: Assign a node to the user who administers it, or clear its owner. The owner (any active user) may then change the node's budgets, drain switch, and name. Work the node is trusted with still follows the owner's role
  • bookclerk nodes invite: Mint a single-use link that enrolls one branch node for a user. The link (with its secret in the URL fragment) is printed once
  • bookclerk nodes invites: List or revoke enrollment links
  • bookclerk nodes revoke: Revoke an enrolled branch node's credential. Its connection closes and it receives no more work

bookclerk nodes list

Every registered node: liveness, artifact target, and labels

bookclerk nodes list [OPTIONS]

bookclerk nodes set

Set a node's scheduling budget or drain it. Applies at that node's next heartbeat

bookclerk nodes set [OPTIONS] [NODE]

Arguments:

  • [NODE]: Node id (default: this node)

Options:

  • --cpu-budget <PERCENT>: Share of detected CPU the scheduler may commit here (1-100)
  • --memory-budget <PERCENT>: Share of detected memory the scheduler may commit here (1-100)
  • --drain: Place nothing new here and move scheduled replicas away
  • --undrain: Accept scheduled replicas again
  • --label <LABEL>: Operator label for the node
  • --cache-budget <BYTES>: Disk space, in bytes, this node's image caches may use, overriding the library's cache.budget_bytes (16 MiB to 1 TiB)
  • --library-cache-budget: Drop this node's cache budget override and follow the library's

bookclerk nodes label

Add or remove placement labels on a node (nas, zone=eu)

bookclerk nodes label [OPTIONS] [NODE]

Arguments:

  • [NODE]: Node id (default: this node)

Options:

  • --add <LABEL>: Label to add. Repeatable
  • --remove <LABEL>: Label to remove. Repeatable
  • --clear: Start from no labels (then apply --add)

bookclerk nodes owner

Assign a node to the user who administers it, or clear its owner. The owner (any active user) may then change the node's budgets, drain switch, and name. Work the node is trusted with still follows the owner's role

bookclerk nodes owner [OPTIONS] [NODE]

Arguments:

  • [NODE]: Node id (default: this node)

Options:

  • --user <USER>: Login name or user id
  • --clear: Remove the node's owner

bookclerk nodes invite

Mint a single-use link that enrolls one branch node for a user. The link (with its secret in the URL fragment) is printed once

bookclerk nodes invite [OPTIONS] --user <USER>

Options:

  • --user <USER>: Login name or user id of the user who will own the branch node (required)
  • --ttl <TTL>: How long the link stays valid (30m, 24h, 7d; 5m to 7d) (default 24h)
  • --label <LABEL>: Label shown in nodes invites list (default ``)

bookclerk nodes invites

List or revoke enrollment links

bookclerk nodes invites [OPTIONS] <COMMAND>

Commands:

bookclerk nodes invites list

Every enrollment link and its state. Secrets are never shown again

bookclerk nodes invites list [OPTIONS]

bookclerk nodes invites revoke

Revoke a link that was not redeemed yet

bookclerk nodes invites revoke [OPTIONS] <LINK_ID>

Arguments:

  • <LINK_ID>: Link id

bookclerk nodes revoke

Revoke an enrolled branch node's credential. Its connection closes and it receives no more work

bookclerk nodes revoke [OPTIONS] <NODE>

Arguments:

  • <NODE>: Branch node id

bookclerk users

The library's people: patron scopes, member controls and Administrator switches

bookclerk users [OPTIONS] <COMMAND>

Commands:

  • bookclerk users scope: Read or set which part of the library a patron sees
  • bookclerk users controls: Read or set what a patron may do: link store accounts, download, edit metadata, upload, request books, see prices
  • bookclerk users admin-controls: Read or set what an Administrator may do: manage members, set patron limits, library-wide scan and acquire, run the job queue, fix the catalog, invite branches, approve requests

bookclerk users scope

Read or set which part of the library a patron sees

bookclerk users scope [OPTIONS] <COMMAND>

Commands:

bookclerk users scope get

Print a patron's scope, or the library's default

bookclerk users scope get [OPTIONS] [USER]

Arguments:

  • [USER]: Login name or user id

Options:

  • --default: The library's default scope, which patrons without their own follow

bookclerk users scope set

Replace a patron's scope, or the library's default. With no --include or --exclude, the scope hides nothing

bookclerk users scope set [OPTIONS] [USER]

Arguments:

  • [USER]: Login name or user id

Options:

  • --default: Set the library's default scope instead of one patron's
  • --include <FIELD=VALUE>: Show only books with this value (genre=Kids); fields are genre, series, author, narrator, tag (a library tag) and collection. Repeatable: a book needs one
  • --exclude <FIELD=VALUE>: Hide books with this value, whatever --include says. Repeatable
  • --hide-explicit: Hide books a store or metadata file marks as explicit content
  • --follow-default: Drop the patron's own scope so they follow the library's default

bookclerk users controls

Read or set what a patron may do: link store accounts, download, edit metadata, upload, request books, see prices

bookclerk users controls [OPTIONS] <COMMAND>

Commands:

bookclerk users controls get

Print a patron's controls, or the library's default

bookclerk users controls get [OPTIONS] [USER]

Arguments:

  • [USER]: Login name or user id

Options:

  • --default: The library's default, which patrons follow unless a control is set for them alone

bookclerk users controls set

Change controls of a patron, or of the library's default. Controls not named keep their value

bookclerk users controls set [OPTIONS] [USER]

Arguments:

  • [USER]: Login name or user id

Options:

  • --default: Change the library's default instead of one patron's controls
  • --allow <CONTROL>: Allow a control (link_accounts, download, edit_metadata, upload, request_books, see_prices). Repeatable
  • --deny <CONTROL>: Turn a control off. Repeatable
  • --follow-default <CONTROL>: Make the patron follow the library's default for a control again. Repeatable; all names every control

bookclerk users admin-controls

Read or set what an Administrator may do: manage members, set patron limits, library-wide scan and acquire, run the job queue, fix the catalog, invite branches, approve requests

bookclerk users admin-controls [OPTIONS] <COMMAND>

Commands:

bookclerk users admin-controls get

Print an Administrator's switches, or the library's default

bookclerk users admin-controls get [OPTIONS] [USER]

Arguments:

  • [USER]: Login name or user id

Options:

  • --default: The library's default, which Administrators follow unless a switch is set for them alone

bookclerk users admin-controls set

Change switches of an Administrator, or of the library's default. Switches not named keep their value

bookclerk users admin-controls set [OPTIONS] [USER]

Arguments:

  • [USER]: Login name or user id

Options:

  • --default: Change the library's default instead of one Administrator's
  • --allow <SWITCH>: Turn a switch on (manage_members, set_patron_limits, library_scan, run_jobs, fix_catalog, invite_branches, approve_requests). Repeatable
  • --deny <SWITCH>: Turn a switch off. Repeatable
  • --follow-default <SWITCH>: Make the Administrator follow the library's default for a switch again. Repeatable; all names every switch

bookclerk queues

Plugin-owned queues on the outbox: counters, consumers, messages

bookclerk queues [OPTIONS] <COMMAND>

Commands:

bookclerk queues list

GET /api/queues — every queue with delivery counters and consumers

bookclerk queues list [OPTIONS]

bookclerk queues inspect

GET /api/queues/{name} — counters, consumers, recent messages and deliveries

bookclerk queues inspect [OPTIONS] <NAME>

Arguments:

  • <NAME>: Queue name (core.events is the domain-event bus)

bookclerk media

What this build's media worker reads and writes

bookclerk media [OPTIONS] <COMMAND>

Commands:

  • bookclerk media capabilities: List the audio codecs, file types and output formats this build's media worker handles (the daemon's GET /api/status/media)

bookclerk media capabilities

List the audio codecs, file types and output formats this build's media worker handles (the daemon's GET /api/status/media)

bookclerk media capabilities [OPTIONS]

bookclerk login

Print a loopback operator sign-in URL (requires a running daemon)

bookclerk login [OPTIONS]

bookclerk diagnostics

Diagnostics ring buffer and opt-in upload

bookclerk diagnostics [OPTIONS] <COMMAND>

Commands:

bookclerk diagnostics show

Print recent diagnostics ring-buffer events

bookclerk diagnostics show [OPTIONS]

Options:

  • -n, --limit <LIMIT>: Max events to print (0 = all) (default 50)

bookclerk diagnostics upload

Upload the current diagnostics ring (requires share_reports + collector URL)

bookclerk diagnostics upload [OPTIONS]

Options:

  • --trigger <TRIGGER>: Trigger label recorded with the report (default cli_manual)

bookclerk diagnostics reset-id

Replace this install's random usage ID (diagnostics.share_usage) with a new one.

The next check-in then counts as a new install. Restart the daemon so its reports carry the new ID.

bookclerk diagnostics reset-id [OPTIONS]

bookclerk diagnostics reports

List the diagnostics reports this install sent, newest first.

Each report ID is what the collector stored and what the GitHub issue for it mentions: search the issues for it, or give it to a maintainer.

The access code beside each ID reads the report back (diagnostics view), deletes the collector's copy (diagnostics delete), and with the ID opens the collector's public lookup page.

bookclerk diagnostics reports [OPTIONS]

Options:

  • -n, --limit <LIMIT>: Max reports to print (0 = all that are kept) (default 20)

bookclerk diagnostics view

Read a sent report back from the collector, with the issues tracking it and its fix.

Uses the access code kept in this install's report history.

bookclerk diagnostics view [OPTIONS] <REPORT_ID>

Arguments:

  • <REPORT_ID>: The report's ID, from bookclerk diagnostics reports

bookclerk diagnostics delete

Delete the collector's stored copy of a sent report.

The collector keeps the report's one-line summary and issue links, so it still counts toward the issue it joined.

bookclerk diagnostics delete [OPTIONS] <REPORT_ID>

Arguments:

  • <REPORT_ID>: The report's ID, from bookclerk diagnostics reports

Options:

  • -y, --yes: Delete without asking (required when stdin is not a terminal)

bookclerk version

Print version information

bookclerk version [OPTIONS]

Source: docs/server/cli-reference.md at main · View as Markdown