---

name: autocaliweb description: Inspect and import content into my self-hosted AutoCaliWeb library. Use for catalog status, search, recent imports, shelves, metadata, or importing an ebook, comic, PDF, or audiobook. allowed-tools: Bash, WebFetch, AskUserQuestion

AutoCaliWeb

Read-only CLI for my self-hosted AutoCaliWeb instance: inspect OPDS status, catalog stats, books, recent imports, shelves, and individual book metadata.

Environment

Credentials are exported into the shell by sops-nix and shell defaults:

• AUTOCALIWEB_URL - base UI/OPDS URL, defaults to http://192.168.1.145:8083
• AUTOCALIWEB_USERNAME - login user
• AUTOCALIWEB_PASSWORD - login password

The autocaliweb CLI reports a JSON error envelope when required env vars are missing.

CLI

Use the installed autocaliweb CLI for common operations. It always emits a single JSON envelope with ok, command, result or error, and next_actions.

autocaliweb                         # command tree and configuration health
autocaliweb status                  # OPDS status and catalog stats
autocaliweb version                 # alias for status
autocaliweb stats                   # database counts
autocaliweb catalog                 # top-level OPDS catalog entries
autocaliweb books --limit 50        # bounded alphabetical book list
autocaliweb recent --limit 25       # recently added books
autocaliweb search "Foundation"     # search books through OPDS
autocaliweb book-info <uuid>        # Calibre Companion metadata
autocaliweb shelves                 # OPDS shelves visible to the user

Workflows

For a book lookup:

1. Run autocaliweb search "<title>" --limit 25.
2. Run autocaliweb book-info <uuid> for the best match.

For import verification:

1. Run autocaliweb recent --limit 10 after AutoCaliWeb has had time to import.
2. If the title is absent, run autocaliweb search "<title>" --limit 25.
3. Do not claim an import completed unless it appears in AutoCaliWeb results.

Workflow: import a book

The user must provide a readable local file or a direct HTTP(S) URL they are allowed to download. Do not search for pirated copies. Confirm before copying because AutoCaliWeb may import, convert, modify metadata, and move the queued file into the Calibre library.

Environment:

• AUTOCALIWEB_INGEST_DIR defaults to /book-ingest.
• AUTOCALIWEB_PROXMOX_HOST defaults to proxmox.
• AUTOCALIWEB_CTID defaults to 101.

Run:

bash scripts/add-book.sh <file-or-url> --dry-run
bash scripts/add-book.sh <file-or-url>

The script copies local files without deleting the original and refuses to overwrite an existing destination. Never copy directly into /calibre-library; AutoCaliWeb and Calibre must update the metadata.

After queuing:

1. Report the ingest destination and that import is asynchronous.
2. After AutoCaliWeb has had time to process it, use autocaliweb recent --limit 10 or autocaliweb search "<title>".
3. Do not claim the import completed until it appears in AutoCaliWeb.

Notes

• Prefer bounded commands with --limit to keep context small.
• If reachable is false in the command tree, surface the CLI error instead of guessing at server state.
• AutoCaliWeb imports asynchronously; an ingest copy means queued, not fully imported.