OpenParable
Skip to content
← Back to skills

Calibredb

Apps & Automation
calibredb

Calibredb is an Agent Skill for apps & automation published in the hashgraph-online/awesome-codex-plugins repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Manage and query Calibre libraries with the calibredb CLI (local paths or Calibre Content server URLs). Use when listing books, searching/filtering library records, reading/updating metadata, adding/removing formats, exporting books, maintaining custom columns, running library checks, managing FTS indexing/search, or creating catalogs/backups from a Calibre library.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/hashgraph-online/awesome-codex-plugins/blob/HEAD/plugins/LVTD-LLC/skills/skills/calibredb/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/calibredb, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

CalibreDB

Use this skill for all command-line operations on Calibre libraries.

Library path

  • Calibre library locations are user-specific. Identify the target library path or Content server URL before running commands.
  • Prefer explicit path in every command: --with-library "$CALIBRE_LIBRARY".
  • If the user has not provided a library path, ask for it or inspect the local environment for an existing Calibre library before proceeding.
  • For machine-readable outputs, use --for-machine or JSON-capable subcommands.

Safety model

Start with read-only operations, then escalate only when needed.

Read-only (safe by default)

  • list
  • search
  • show_metadata
  • custom_columns
  • list_categories
  • check_library
  • fts_search
  • fts_index status

Mutating (confirm intent for destructive/irreversible)

  • Usually safe with clear intent: add, set_metadata, set_custom, add_format, embed_metadata, backup_metadata
  • Confirm before destructive actions: remove, remove_format, remove_custom_column, restore_database, fts_index reindex on full library

Core workflow

  1. Identify target library and set --with-library.
  2. Discover relevant book IDs with search (or list --search).
  3. Inspect records with show_metadata or list --for-machine.
  4. Apply minimal required mutations.
  5. Validate with follow-up list/search/show_metadata.

Quick command patterns

1) List books

export CALIBRE_LIBRARY="/path/to/Calibre Library"
calibredb list --with-library "$CALIBRE_LIBRARY" --fields id,title,authors,formats --limit 20

Machine output:

calibredb list --with-library "$CALIBRE_LIBRARY" --fields id,title,authors,tags,formats --for-machine

2) Search and get IDs

calibredb search --with-library "$CALIBRE_LIBRARY" "title:python"

Use IDs in follow-up commands.

3) Show metadata

calibredb show_metadata --with-library "$CALIBRE_LIBRARY" 123

As OPF:

calibredb show_metadata --with-library "$CALIBRE_LIBRARY" --as-opf 123

4) Update metadata fields

calibredb set_metadata --with-library "$CALIBRE_LIBRARY" 123 \
  --field title:"Example Book" \
  --field tags:"python,reference"

5) Add/export books

calibredb add --with-library "$CALIBRE_LIBRARY" "/path/to/book.epub"
calibredb export --with-library "$CALIBRE_LIBRARY" 123 --to-dir "/tmp/export"

6) Library health check

calibredb check_library --with-library "$CALIBRE_LIBRARY"

Content server usage

To target a running Calibre Content server:

calibredb list --with-library "http://hostname:8080/#library_id" --username <user> --password <pass>

From docs: use special #- library id to list server libraries.

Security note: a literal --password <pass> value is passed as a process argument and may be visible to other users on shared machines via process-listing tools. Prefer --password '<stdin>' with the password piped from a password manager, or --password '<f:/path/to/file>' with a 0600 credential file stored outside the repository. Prefer local or trusted hosts for authenticated Content server commands, and redact credentials from shell history, logs, and task transcripts.

Reference files

  • Command matrix + options: references/command-matrix.md
  • Safe operational playbooks: references/safe-workflows.md