### Manually install TomeSync plugin Source: https://tome.bndct.sh/docs/koreader Commands to install the plugin on macOS or Linux systems. ```bash cd ~/.koreader/plugins cp ~/Downloads/tomesync.koplugin.zip . unzip tomesync.koplugin.zip ``` -------------------------------- ### Install Scribe Skill Source: https://tome.bndct.sh/docs/scribe Run the installation script within the local Tome checkout to symlink the skill for Claude Code. ```bash # In your local Tome checkout: ./skills/scribe/install.sh # That symlinks skills/scribe into ~/.claude/skills/scribe so Claude Code # picks up the /scribe slash command on next launch. ``` -------------------------------- ### Quick-start Installation Script Source: https://tome.bndct.sh/docs/installation Executes a shell script to automatically set up a temporary Tome instance for testing. ```bash curl -fsSL https://tome.bndct.sh/install.sh | bash ``` -------------------------------- ### GET /api/users Source: https://tome.bndct.sh/docs/api Lists all users in the system. ```APIDOC ## GET /api/users ### Description Lists all users in the system. ### Method GET ### Endpoint /api/users ``` -------------------------------- ### Caddy Reverse Proxy Configuration Source: https://tome.bndct.sh/docs/installation Example configuration for exposing Tome via Caddy. ```caddy tome.example.com { reverse_proxy localhost:8080 } ``` -------------------------------- ### GET /api/auth/me Source: https://tome.bndct.sh/docs/api Verifies the current authentication token. ```APIDOC ## GET /api/auth/me ### Description Verifies the current authentication token. ### Method GET ### Endpoint /api/auth/me ``` -------------------------------- ### GET /api/book-types Source: https://tome.bndct.sh/docs/api List all book types. ```APIDOC ## GET /api/book-types ### Description List all book types. ### Method GET ### Endpoint /api/book-types ``` -------------------------------- ### GET /api/tome-sync/position/{book_id} Source: https://tome.bndct.sh/docs/api Get reading position for a book. ```APIDOC ## GET /api/tome-sync/position/{book_id} ### Description Get reading position for a book. ### Method GET ### Endpoint /api/tome-sync/position/{book_id} ``` -------------------------------- ### GET /api/tome-sync/series Source: https://tome.bndct.sh/docs/api List series available for download. ```APIDOC ## GET /api/tome-sync/series ### Description List series available for download. ### Method GET ### Endpoint /api/tome-sync/series ``` -------------------------------- ### GET /api/home/forgotten-books Source: https://tome.bndct.sh/docs/api Retrieves a list of books that were started but have not been interacted with recently. ```APIDOC ## GET /api/home/forgotten-books ### Description Retrieves a list of books that were started but have not been interacted with recently. ### Method GET ### Endpoint /api/home/forgotten-books ``` -------------------------------- ### GET /api/home/activity Source: https://tome.bndct.sh/docs/api Retrieves a list of recent reading activity. ```APIDOC ## GET /api/home/activity ### Description Retrieves a list of recent reading activity. ### Method GET ### Endpoint /api/home/activity ``` -------------------------------- ### GET /api/libraries Source: https://tome.bndct.sh/docs/api List libraries visible to the current user. ```APIDOC ## GET /api/libraries ### Description List libraries visible to current user. ### Method GET ### Endpoint /api/libraries ``` -------------------------------- ### GET /api/admin/stats Source: https://tome.bndct.sh/docs/api Retrieves system-wide reading statistics. ```APIDOC ## GET /api/admin/stats ### Description Retrieves system-wide reading statistics. ### Method GET ### Endpoint /api/admin/stats ``` -------------------------------- ### GET /api/tome-sync/download/{book_id}/{file_id} Source: https://tome.bndct.sh/docs/api Download file (KOReader format). ```APIDOC ## GET /api/tome-sync/download/{book_id}/{file_id} ### Description Download file (KOReader format). ### Method GET ### Endpoint /api/tome-sync/download/{book_id}/{file_id} ``` -------------------------------- ### GET /api/admin/duplicates Source: https://tome.bndct.sh/docs/api Detects duplicate books in the library. ```APIDOC ## GET /api/admin/duplicates ### Description Detects duplicate books in the library. ### Method GET ### Endpoint /api/admin/duplicates ``` -------------------------------- ### GET /api/admin/audit-logs Source: https://tome.bndct.sh/docs/api Retrieves audit log entries. ```APIDOC ## GET /api/admin/audit-logs ### Description Retrieves audit log entries. ### Method GET ### Endpoint /api/admin/audit-logs ``` -------------------------------- ### GET /api/tome-sync/resolve Source: https://tome.bndct.sh/docs/api Resolve a file hash to a canonical book ID. ```APIDOC ## GET /api/tome-sync/resolve ### Description Resolve a file hash to a canonical book ID. ### Method GET ### Endpoint /api/tome-sync/resolve ``` -------------------------------- ### GET /api/books Source: https://tome.bndct.sh/docs/api Lists books in the library with optional filtering. ```APIDOC ## GET /api/books ### Description List books in the library. Supports filtering via query parameters. ### Method GET ### Endpoint /api/books ### Parameters #### Query Parameters - **q** (string) - Optional - Search query - **series** (string) - Optional - Filter by series - **author** (string) - Optional - Filter by author - **library_id** (string) - Optional - Filter by library ID - **per_page** (integer) - Optional - Results per page ``` -------------------------------- ### GET /api/stats/completion-estimates Source: https://tome.bndct.sh/docs/stats Retrieves projected finish dates for in-progress books. ```APIDOC ## GET /api/stats/completion-estimates ### Description Retrieves projected finish dates for in-progress books. ### Method GET ### Endpoint /api/stats/completion-estimates ``` -------------------------------- ### GET /api/saved-filters Source: https://tome.bndct.sh/docs/api List current user's shelves. ```APIDOC ## GET /api/saved-filters ### Description List current user's shelves. ### Method GET ### Endpoint /api/saved-filters ``` -------------------------------- ### GET /api/books/{id} Source: https://tome.bndct.sh/docs/api Retrieves detailed information about a specific book. ```APIDOC ## GET /api/books/{id} ### Description Retrieve book detail including files, tags, and libraries. ### Method GET ### Endpoint /api/books/{id} ### Parameters #### Path Parameters - **id** (string) - Required - The unique identifier of the book ``` -------------------------------- ### GET /api/stats Source: https://tome.bndct.sh/docs/stats Retrieves the main bundle of statistics for a specified number of days. ```APIDOC ## GET /api/stats ### Description Retrieves the main bundle of statistics for the specified timeframe. ### Method GET ### Endpoint /api/stats ### Parameters #### Query Parameters - **days** (integer) - Optional - Number of days to include in the stats. - **tz_offset** (integer) - Optional - Timezone offset in minutes. ``` -------------------------------- ### GET /api/stats/timeline Source: https://tome.bndct.sh/docs/stats Retrieves lifetime per-book reading spans and active days. ```APIDOC ## GET /api/stats/timeline ### Description Retrieves lifetime per-book reading spans and active days. ### Method GET ### Endpoint /api/stats/timeline ``` -------------------------------- ### GET /api/home/stats Source: https://tome.bndct.sh/docs/api Retrieves dashboard summary information including reading streak, pages read, and total reading time. ```APIDOC ## GET /api/home/stats ### Description Retrieves dashboard summary information including reading streak, pages read, and total reading time. ### Method GET ### Endpoint /api/home/stats ``` -------------------------------- ### POST /api/libraries Source: https://tome.bndct.sh/docs/api Create a new library. ```APIDOC ## POST /api/libraries ### Description Create library (name, icon, is_public). ### Method POST ### Endpoint /api/libraries ``` -------------------------------- ### Docker Compose Configuration Source: https://tome.bndct.sh/docs/installation Standard configuration for running Tome with persistent volumes for data, books, and the bindery. ```yaml services: tome: image: ghcr.io/bndct-devops/tome:latest container_name: tome ports: - "8080:8080" volumes: - ./data:/data - ./books:/books - ./bindery:/bindery environment: # Optional. Auto-generated if unset — see /docs/configuration # - TOME_SECRET_KEY= # Optional. Better metadata. Get a free token at hardcover.app # - TOME_HARDCOVER_TOKEN= restart: unless-stopped ``` -------------------------------- ### POST /api/books/reorganize Source: https://tome.bndct.sh/docs/api Moves files to their canonical paths. ```APIDOC ## POST /api/books/reorganize ### Description Moves files to their canonical paths. ### Method POST ### Endpoint /api/books/reorganize ``` -------------------------------- ### Configure SMTP environment variables Source: https://tome.bndct.sh/docs/send-to-device Set these environment variables on the server to enable the Send to device feature. The feature is active once host, user, and password variables are provided. ```text TOME_SMTP_HOST=smtp.fastmail.com TOME_SMTP_PORT=587 TOME_SMTP_USER=you@fastmail.com TOME_SMTP_PASSWORD=your-app-password ``` ```text TOME_SMTP_HOST=smtp.gmail.com TOME_SMTP_PORT=587 TOME_SMTP_USER=you@gmail.com TOME_SMTP_PASSWORD=your-app-password ``` ```text TOME_SMTP_HOST=smtp.example.com TOME_SMTP_PORT=587 TOME_SMTP_USER=tome@example.com TOME_SMTP_PASSWORD=secret TOME_SMTP_FROM=tome@example.com # optional, defaults to TOME_SMTP_USER ``` -------------------------------- ### Configure Bindery for Manual Review Source: https://tome.bndct.sh/docs/bindery The default configuration for the Tome service, requiring manual intervention for file ingestion. ```yaml # docker-compose.yml — manual review (default) services: tome: image: ghcr.io/bndct-devops/tome:latest volumes: - ./data:/data - ./books:/books - ./bindery:/bindery # ← drop files here # No TOME_AUTO_IMPORT — manual is the default ``` -------------------------------- ### Configure Tome OIDC Environment Variables Source: https://tome.bndct.sh/docs/sso Set these environment variables on the Tome container to enable OIDC authentication. Ensure the container is restarted after applying these changes. ```bash TOME_OIDC_ENABLED=true TOME_OIDC_ISSUER=https://auth.example.com TOME_OIDC_CLIENT_ID= TOME_OIDC_CLIENT_SECRET= TOME_OIDC_ADMIN_GROUP=tome_admins TOME_OIDC_MEMBER_GROUP=tome_members TOME_OIDC_DEFAULT_ROLE=guest # Behind a reverse proxy, pin your public origin so the redirect is correct: TOME_PUBLIC_URL=https://tome.example.com ``` -------------------------------- ### Verify Authentication Token Source: https://tome.bndct.sh/docs/api Use this command to validate that your bearer token is correctly configured for API access. ```bash curl -H "Authorization: Bearer $TOKEN" https://your-tome/api/auth/me ``` -------------------------------- ### POST /api/book-types Source: https://tome.bndct.sh/docs/api Create a book type. ```APIDOC ## POST /api/book-types ### Description Create book type (admin). ### Method POST ### Endpoint /api/book-types ``` -------------------------------- ### GET /api/stats/sessions Source: https://tome.bndct.sh/docs/stats Retrieves a paged list of reading sessions. ```APIDOC ## GET /api/stats/sessions ### Description Retrieves a paged session list, oldest first. ### Method GET ### Endpoint /api/stats/sessions ``` -------------------------------- ### POST /api/tome-sync/session Source: https://tome.bndct.sh/docs/api Record a reading session. ```APIDOC ## POST /api/tome-sync/session ### Description Record a reading session. ### Method POST ### Endpoint /api/tome-sync/session ``` -------------------------------- ### GET /api/books/library-health Source: https://tome.bndct.sh/docs/api Generates a report of misplaced files in the library. ```APIDOC ## GET /api/books/library-health ### Description Generates a report of misplaced files in the library. ### Method GET ### Endpoint /api/books/library-health ``` -------------------------------- ### POST /api/libraries/{id}/users Source: https://tome.bndct.sh/docs/api Assign a user to a library. ```APIDOC ## POST /api/libraries/{id}/users ### Description Assign user to library (admin). ### Method POST ### Endpoint /api/libraries/{id}/users ``` -------------------------------- ### POST /api/books/upload Source: https://tome.bndct.sh/docs/api Uploads a new book file to the library. ```APIDOC ## POST /api/books/upload ### Description Upload a file to the library. Uses multipart form data. ### Method POST ### Endpoint /api/books/upload ### Parameters #### Request Body - **file** (file) - Required - The book file to upload - **book_type_id** (string) - Optional - The type ID for the book ``` -------------------------------- ### Configure Homepage dashboard widget for Tome Source: https://tome.bndct.sh/docs/api-tokens Integrate Tome reading statistics into a Homepage dashboard using the customapi widget. ```yaml - Tome: icon: mdi-book-open-page-variant href: https://your-tome.example.com widget: type: customapi url: https://your-tome.example.com/api/home/stats headers: Authorization: Bearer tome_xxxxxxxx mappings: - field: current_streak_days label: Streak suffix: " days" - field: books_finished_30d label: Finished (30d) - field: reading_seconds_30d label: Read (30d) format: duration - field: pages_turned_30d label: Pages (30d) ``` -------------------------------- ### POST /api/users Source: https://tome.bndct.sh/docs/api Creates a new user. ```APIDOC ## POST /api/users ### Description Creates a new user. ### Method POST ### Endpoint /api/users ``` -------------------------------- ### Promote User to Admin via Database Source: https://tome.bndct.sh/docs/troubleshooting Directly update a user's role to admin in the database to regain access to restricted features. ```bash docker exec -it tome sqlite3 /data/tome.db "UPDATE users SET role='admin', is_admin=1 WHERE username='';" ``` -------------------------------- ### POST /api/auth/login Source: https://tome.bndct.sh/docs/api Authenticates the user and returns a JWT. ```APIDOC ## POST /api/auth/login ### Description Authenticate the user and return a JWT for subsequent requests. ### Method POST ### Endpoint /api/auth/login ``` -------------------------------- ### POST /api/books/purge-empty-dirs Source: https://tome.bndct.sh/docs/api Cleans up empty directories in the library. ```APIDOC ## POST /api/books/purge-empty-dirs ### Description Cleans up empty directories in the library. ### Method POST ### Endpoint /api/books/purge-empty-dirs ``` -------------------------------- ### POST /api/libraries/{id}/books Source: https://tome.bndct.sh/docs/api Add books to a library. ```APIDOC ## POST /api/libraries/{id}/books ### Description Add books to library. ### Method POST ### Endpoint /api/libraries/{id}/books ### Parameters #### Path Parameters - **id** (string) - Required - The ID of the library. #### Request Body - **book_ids** (array) - Required - List of book IDs to add. ``` -------------------------------- ### PUT /api/libraries/{id} Source: https://tome.bndct.sh/docs/api Update an existing library. ```APIDOC ## PUT /api/libraries/{id} ### Description Update library. ### Method PUT ### Endpoint /api/libraries/{id} ### Parameters #### Path Parameters - **id** (string) - Required - The ID of the library to update. ``` -------------------------------- ### Update Tome Container Source: https://tome.bndct.sh/docs/installation Command to pull the latest image and restart the container while preserving data. ```bash docker compose pull && docker compose up -d ``` -------------------------------- ### Authenticate with API tokens using curl Source: https://tome.bndct.sh/docs/api-tokens Use the Authorization header with a Bearer token to authenticate API requests. ```bash # Replace TOKEN with your tome_… secret curl -H "Authorization: Bearer $TOKEN" \ https://your-tome.example.com/api/books?limit=5 ``` -------------------------------- ### Configure Scribe Authentication Source: https://tome.bndct.sh/docs/scribe Define API tokens and base URLs for different Tome instances in the scribe.json configuration file. ```json # ~/.config/tome/scribe.json — multi-profile config { "profiles": { "dev": { "base_url": "http://localhost:8080", "token": "tome_dev_…" }, "prod": { "base_url": "https://tome.example.com", "token": "tome_prod_…" } }, "default": "dev" } ``` -------------------------------- ### POST /api/users/{id}/impersonate Source: https://tome.bndct.sh/docs/api Impersonates a user and returns their JWT. ```APIDOC ## POST /api/users/{id}/impersonate ### Description Impersonates a user and returns their JWT. ### Method POST ### Endpoint /api/users/{id}/impersonate ### Parameters #### Path Parameters - **id** (string) - Required - The unique identifier of the user. ``` -------------------------------- ### Catppuccin Mocha Color Palette Source: https://tome.bndct.sh/docs/themes Hex values for the Catppuccin Mocha theme configuration. ```text #1E1E2E, #CDD6F4, #313244, #CBA6F7, #1E1E2E, #45475A, #A6ADC8, #B4BEFE, #45475A, #F38BA8 ``` -------------------------------- ### PUT /api/saved-filters/{id} Source: https://tome.bndct.sh/docs/api Update shelf name or icon. ```APIDOC ## PUT /api/saved-filters/{id} ### Description Update shelf name / icon. ### Method PUT ### Endpoint /api/saved-filters/{id} ``` -------------------------------- ### Nord Color Palette Source: https://tome.bndct.sh/docs/themes Hex values for the Nord theme configuration. ```text #2E3440, #D8DEE9, #3B4252, #88C0D0, #2E3440, #4C566A, #D8DEE9, #81A1C1, #4C566A, #BF616A ``` -------------------------------- ### POST /api/admin/duplicates/dismiss Source: https://tome.bndct.sh/docs/api Dismisses a duplicate book pair. ```APIDOC ## POST /api/admin/duplicates/dismiss ### Description Dismisses a duplicate book pair. ### Method POST ### Endpoint /api/admin/duplicates/dismiss ``` -------------------------------- ### PUT /api/tome-sync/position/{book_id} Source: https://tome.bndct.sh/docs/api Update reading position. ```APIDOC ## PUT /api/tome-sync/position/{book_id} ### Description Update reading position. ### Method PUT ### Endpoint /api/tome-sync/position/{book_id} ``` -------------------------------- ### POST /api/admin/duplicates/merge Source: https://tome.bndct.sh/docs/api Merges a pair of duplicate books. ```APIDOC ## POST /api/admin/duplicates/merge ### Description Merges a pair of duplicate books. ### Method POST ### Endpoint /api/admin/duplicates/merge ``` -------------------------------- ### PUT /api/book-types/{id} Source: https://tome.bndct.sh/docs/api Update a book type. ```APIDOC ## PUT /api/book-types/{id} ### Description Update book type. ### Method PUT ### Endpoint /api/book-types/{id} ``` -------------------------------- ### DELETE /api/libraries/{id}/books/{book_id} Source: https://tome.bndct.sh/docs/api Remove a book from a library. ```APIDOC ## DELETE /api/libraries/{id}/books/{book_id} ### Description Remove book from library. ### Method DELETE ### Endpoint /api/libraries/{id}/books/{book_id} ### Parameters #### Path Parameters - **id** (string) - Required - The ID of the library. - **book_id** (string) - Required - The ID of the book to remove. ``` -------------------------------- ### PUT /api/books/{id}/status Source: https://tome.bndct.sh/docs/api Updates the reading status and progress for a book. ```APIDOC ## PUT /api/books/{id}/status ### Description Set the reading status, progress, and CFI for a specific book. ### Method PUT ### Endpoint /api/books/{id}/status ### Parameters #### Path Parameters - **id** (string) - Required - The unique identifier of the book ``` -------------------------------- ### DELETE /api/libraries/{id}/users/{user_id} Source: https://tome.bndct.sh/docs/api Remove a user from a library. ```APIDOC ## DELETE /api/libraries/{id}/users/{user_id} ### Description Remove user from library (admin). ### Method DELETE ### Endpoint /api/libraries/{id}/users/{user_id} ``` -------------------------------- ### Dashboard Management Source: https://tome.bndct.sh/docs/stats Endpoints for retrieving and updating saved dashboard layouts. ```APIDOC ## GET /api/stats/dashboard ### Description Retrieves saved dashboard layouts. ### Method GET ### Endpoint /api/stats/dashboard ## PUT /api/stats/dashboard ### Description Updates saved dashboard layouts. ### Method PUT ### Endpoint /api/stats/dashboard ``` -------------------------------- ### POST /api/saved-filters Source: https://tome.bndct.sh/docs/api Save current filter params as a shelf. ```APIDOC ## POST /api/saved-filters ### Description Save current filter params as a shelf. ### Method POST ### Endpoint /api/saved-filters ```