Calibredb

https://manual.calibre-ebook.com/generated/en/calibredb.html
Admin
Calibredb is the command-line interface to the Calibre database, used to manipulate e-book libraries...
Tokens:11,980
Snippets:173
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### calibredb command syntax

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Shows the general syntax for invoking the calibredb command-line tool. Use this as the starting point for any calibredb operation, replacing 'command' with a sub-command and providing appropriate options and arguments.

```bash
calibredb command [options] [arguments]

```

--------------------------------

### calibredb list command

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Lists the books available in the calibre database. Enclose arguments with spaces in quotation marks, for example: "/some path/with spaces".

```bash
calibredb list [options]

```

--------------------------------

### Set custom column value with calibredb set_custom

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Sets the value of a custom column for the book identified by id. Use --append, -a to append values to existing ones for multi-value columns. Get ids with the search command and column names with custom_columns. Enclose arguments with spaces in quotation marks.

```bash
calibredb set_custom [options] column id value

```

--------------------------------

### Restore database with calibredb restore_database

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Restores the database from metadata in OPF files. Requires --really-do-it, -r to run. Warning: completely regenerates the database, losing saved searches, user categories, plugboards, per-book conversion settings, and custom recipes. Enclose arguments with spaces in quotation marks.

```bash
calibredb restore_database [options]

```

--------------------------------

### calibredb backup_metadata command syntax

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Backs up metadata from the database into individual OPF files in each book's folder. Normally runs automatically, but this command forces regeneration. Use --all to operate on all books instead of only those with out-of-date OPF files.

```bash
calibredb backup_metadata [options]

```

--------------------------------

### calibredb add command

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Adds specified files as books to the database. Folders can be added with folder-related options. Enclose arguments with spaces in quotation marks.

```bash
calibredb add [options] file1 file2 file3 ...

```

--------------------------------

### calibredb clone command syntax

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Creates a new, empty library that has the same custom columns, Virtual libraries, and other settings as the current library. The cloned library contains no books; use filesystem tools to copy the library folder for a full duplicate.

```bash
calibredb clone path/to/new/library

```

--------------------------------

### calibredb add_format command

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Adds the e-book in ebook_file to the available formats for the logical book identified by id. If the format already exists, it is replaced unless --dont-replace is specified. Use --as-extra-data-file to add the file as an extra data file instead of an ebook format.

```bash
calibredb add_format [options] id ebook_file

```

--------------------------------

### List custom columns with calibredb custom_columns

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Lists available custom columns, showing column labels and ids. Use --details, -d to show details for each column. Enclose arguments with spaces in quotation marks.

```bash
calibredb custom_columns [options]

```

--------------------------------

### calibredb add_custom_column command syntax

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Shows the general syntax for the add_custom_column subcommand, which creates a custom column. Requires label, name, and datatype arguments.

```bash
calibredb add_custom_column [options] label name datatype

```

--------------------------------

### Run calibredb list_categories command

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Generates a report of category information from the Calibre database, similar to the Tag browser. Enclose arguments with spaces in quotation marks. Options include --categories, --csv, --dialect, --item_count, and --width.

```bash
calibredb list_categories [options]

```

--------------------------------

### calibredb clone

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Create a clone of the current library with all settings but no books. The new library is created at the specified path.

```APIDOC
## clone

### Description
Create a clone of the current library. This creates a new, empty library that has all the same custom columns, Virtual libraries and other settings as the current library. The cloned library will contain no books.

### Method
calibredb clone

### Endpoint
calibredb clone path/to/new/library

### Parameters
#### Arguments
- **path/to/new/library** (string) - Required - The path where the new library will be created.

### Notes
Whenever you pass arguments to calibredb that have spaces in them, enclose the arguments in quotation marks. For example: "/some path/with spaces"
```

--------------------------------

### calibredb catalog command

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Exports a catalog in the format determined by the destination file extension. Options control how entries are displayed, and different catalog formats support different option sets. Enclose arguments with spaces in quotation marks.

```bash
calibredb catalog /path/to/destination.(csv|epub|mobi|xml...) [options]

```

--------------------------------

### calibredb restore_database

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Restores the database from metadata stored in OPF files. Requires the --really-do-it option to execute.

```APIDOC
## calibredb restore_database

### Description
Restore this database from the metadata stored in OPF files in each folder of the calibre library. This is useful if your metadata.db file has been corrupted.

WARNING: This command completely regenerates your database. You will lose all saved searches, user categories, plugboards, stored per-book conversion settings, and custom recipes. Restored metadata will only be as accurate as what is found in the OPF files.

### Method
CLI

### Endpoint
calibredb restore_database [options]

### Parameters
#### Options
- **--really-do-it, -r** - Required - Really do the recovery. The command will not run unless this option is specified.

### Notes
Whenever you pass arguments to calibredb that have spaces in them, enclose the arguments in quotation marks. For example: "/some path/with spaces"
```

--------------------------------

### calibredb export command

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Exports the books specified by ids (a comma separated list) to the filesystem. Saves all formats, cover, metadata in an OPF file, and extra data files. Enclose arguments with spaces in quotation marks.

```bash
calibredb export [options] ids

```

--------------------------------

### calibredb show_metadata command

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Shows the metadata stored in the calibre database for the book identified by id. The id is a book id number from the search command. Enclose arguments with spaces in quotation marks.

```bash
calibredb show_metadata [options] id
```

--------------------------------

### calibredb set_metadata command

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Sets the metadata stored in the calibre database for the book identified by book_id from the OPF file metadata.opf. book_id is a book id number from the search command. You can also set individual fields with the --field option, in which case no OPF file is needed. Enclose arguments with spaces in quotation marks.

```bash
calibredb set_metadata [options] book_id [/path/to/metadata.opf]
```

--------------------------------

### calibredb embed_metadata command syntax

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Updates metadata in the actual book files from the calibre database. Use 'all' for book_id to update all books, or specify multiple ids and ranges (e.g., 1 2 10-15 23). Use --only-formats to limit updates to specific formats.

```bash
calibredb embed_metadata [options] book_id

```

--------------------------------

### calibredb search command

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Searches the library for the specified search term and returns a comma-separated list of book ids. The search expression can use calibre's search query language, e.g., calibredb search author:asimov 'title:"i robot"'. Enclose arguments with spaces in quotation marks. Use --limit, -l to cap the number of results (default: all).

```bash
calibredb search [options] search expression
```

--------------------------------

### Run calibredb check_library command

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Runs integrity checks on a Calibre library filesystem, reporting issues such as invalid titles, extra files, missing formats, and malformed paths. Enclose any arguments containing spaces in quotation marks. Options include --csv, --ignore_extensions, --ignore_names, --report, and --vacuum-fts-db.

```bash
calibredb check_library [options]

```

--------------------------------

### calibredb fts_search command syntax

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Use this command to perform a full text search on the entire library or a subset. Enclose arguments with spaces in quotation marks.

```text
calibredb fts_search [options] search expression

```

--------------------------------

### calibredb backup_metadata

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Backup metadata from the calibre database into individual OPF files in each book's folder. Use the --all option to force regeneration for all books.

```APIDOC
## backup_metadata

### Description
Backup the metadata stored in the database into individual OPF files in each books folder. This normally happens automatically, but you can run this command to force re-generation of the OPF files, with the --all option.

### Method
calibredb backup_metadata

### Endpoint
calibredb backup_metadata [options]

### Parameters
#### Options
- **--all** - Optional - Normally, this command only operates on books that have out of date OPF files. This option makes it operate on all books.

### Notes
Whenever you pass arguments to calibredb that have spaces in them, enclose the arguments in quotation marks. For example: "/some path/with spaces"
```

--------------------------------

### calibredb fts_index command

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Controls the Full Text Search indexing process. Subcommands: enable (turns on FTS indexing), disable (turns off), status (shows current status), reindex (re-indexes specified book ids or the entire library if none given). Use --indexing-speed to choose fast or slow (reset to slow after each invocation) and --wait-for-completion to wait until all books are indexed.

```bash
calibredb fts_index [options] enable/disable/status/reindex
```

--------------------------------

### calibredb saved_searches command syntax

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Shows the general syntax for the saved_searches subcommand, which manages saved searches in the database. Options are followed by the action (list, add, or remove).

```bash
calibredb saved_searches [options] (list|add|remove)

```

--------------------------------

### calibredb show_metadata

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Shows the metadata stored in the calibre database for the book identified by the given id. The id is a book id number from the search command. The --as-opf option prints metadata in OPF form (XML).

```APIDOC
## calibredb show_metadata

### Description
Shows the metadata stored in the calibre database for the book identified by the given id.

### Method
calibredb command

### Endpoint
calibredb show_metadata [options] id

### Parameters
#### Positional Parameters
- **id** (integer) - Required - The book id number from the search command.

#### Options
- **--as-opf** - Optional - Print metadata in OPF form (XML).

### Notes
Whenever you pass arguments to calibredb that have spaces in them, enclose the arguments in quotation marks.
```

--------------------------------

### calibredb remove_format command

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Removes the format fmt from the logical book identified by id. fmt should be a file extension like LRF, TXT, or EPUB. If the logical book does not have fmt available, the command does nothing.

```bash
calibredb remove_format [options] id fmt

```

--------------------------------

### calibredb add

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Adds specified files as books to the Calibre database. Supports options for setting metadata and controlling folder scanning.

```APIDOC
## calibredb add

### Description
Add the specified files as books to the database. You can also specify folders, see the folder related options below.

### Usage
`calibredb add [options] file1 file2 file3 ...`

### Options

#### --authors, -a
Set the authors of the added book(s).

#### --automerge, -m
If books with similar titles and authors are found, merge the incoming formats (files) automatically into existing book records. Values: `ignore` (duplicate formats discarded), `overwrite` (duplicate formats in the library are overwritten), `new_record` (duplicate formats placed into a new book record).

#### --cover, -c
Path to the cover to use for the added book.

#### --duplicates, -d
Add books to database even if they already exist. Comparison is done based on book titles and authors. Note that the `--automerge` option takes precedence.

#### --empty, -e
Add an empty book (a book with no formats).

#### --identifier, -I
Set the identifiers for this book, e.g. -I asin:XXX -I isbn:YYY.

#### --isbn, -i
Set the ISBN of the added book(s).

#### --languages, -l
A comma separated list of languages (best to use ISO639 language codes, though some language names may also be recognized).

#### --series, -s
Set the series of the added book(s).

#### --series-index, -S
Set the series number of the added book(s).

#### --tags, -T
Set the tags of the added book(s).

#### --title, -t
Set the title of the added book(s).

### Adding From Folders
Options to control the adding of books from folders. By default only files that have extensions of known e-book file types are added.

#### --add
A filename (glob) pattern, files matching this pattern will be added when scanning folders for files, even if they are not of a known e-book file type. Can be specified multiple times for multiple patterns.

#### --ignore
A filename (glob) pattern, files matching this pattern will be ignored when scanning folders for files. Can be specified multiple times for multiple patterns. For example: *.pdf will ignore all PDF files.

#### --one-book-per-directory, -1
Assume that each folder has only a single logical book and that all files in it are different e-book formats of that book.

#### --recurse, -r
Process folders recursively.
```

--------------------------------

### calibredb custom_columns

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Lists available custom columns, showing column labels and ids. Optionally shows details for each column.

```APIDOC
## calibredb custom_columns

### Description
List available custom columns. Shows column labels and ids.

### Method
CLI

### Endpoint
calibredb custom_columns [options]

### Parameters
#### Options
- **--details, -d** - Optional - Show details for each column.

### Notes
Whenever you pass arguments to calibredb that have spaces in them, enclose the arguments in quotation marks. For example: "/some path/with spaces"
```

--------------------------------

### calibredb remove command

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Removes the books identified by ids from the database. ids should be a comma separated list of id numbers, e.g., 23,34,57-85 (the last number in a range is not included). Use the --permanent option to skip the Recycle Bin.

```bash
calibredb remove ids

```

--------------------------------

### calibredb add_format

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Adds a new e-book format to an existing book in the Calibre database. Can optionally add as an extra data file or avoid replacing an existing format.

```APIDOC
## calibredb add_format

### Description
Add the e-book in ebook_file to the available formats for the logical book identified by id. You can get id by using the search command. If the format already exists, it is replaced, unless the do not replace option is specified.

### Method
add_format

### Endpoint
calibredb add_format [options] id ebook_file

### Parameters
#### Path Parameters
- **id** (string) - Required - The logical book ID.
- **ebook_file** (string) - Required - Path to the e-book file to add.

#### Options
- **--as-extra-data-file** (flag) - Optional - Add the file as an extra data file to the book, not an ebook format.
- **--dont-replace** (flag) - Optional - Do not replace the format if it already exists.

### Notes
Whenever you pass arguments to calibredb that have spaces in them, enclose the arguments in quotation marks. For example: "/some path/with spaces".
```

--------------------------------

### calibredb set_metadata

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Sets the metadata stored in the calibre database for the book identified by book_id from the OPF file metadata.opf. You can also set individual fields with the --field option. The --list-fields option lists available field names.

```APIDOC
## calibredb set_metadata

### Description
Sets the metadata stored in the calibre database for the book identified by book_id from the OPF file metadata.opf. You can also set individual fields with the --field option.

### Method
calibredb command

### Endpoint
calibredb set_metadata [options] book_id [/path/to/metadata.opf]

### Parameters
#### Positional Parameters
- **book_id** (integer) - Required - The book id number from the search command.
- **/path/to/metadata.opf** (string) - Optional - Path to the OPF file containing metadata. Not needed if using --field.

#### Options
- **--field, -f** - Optional - The field to set. Format is field_name:value, for example: `--field` tags:tag1,tag2. Can be specified multiple times. For languages use ISO639 language codes. For identifiers use syntax: `--field` identifiers:isbn:XXXX,doi:YYYYY. For boolean fields use true/false or yes/no.
- **--list-fields, -l** - Optional - List the metadata field names that can be used with the --field option.

### Notes
Whenever you pass arguments to calibredb that have spaces in them, enclose the arguments in quotation marks.
```

--------------------------------

### calibredb set_custom

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Sets the value of a custom column for a specified book ID. Can append values if the column stores multiple values.

```APIDOC
## calibredb set_custom

### Description
Set the value of a custom column for the book identified by id. You can get a list of ids using the search command. You can get a list of custom column names using the custom_columns command.

### Method
CLI

### Endpoint
calibredb set_custom [options] column id value

### Parameters
#### Options
- **--append, -a** - Optional - If the column stores multiple values, append the specified values to the existing ones, instead of replacing them.

#### Arguments
- **column** - Required - The name of the custom column.
- **id** - Required - The identifier of the book.
- **value** - Required - The value to set.

### Notes
Whenever you pass arguments to calibredb that have spaces in them, enclose the arguments in quotation marks. For example: "/some path/with spaces"
```

--------------------------------

### calibredb fts_index

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Control the Full text search indexing process. The command accepts one of the following subcommands: enable, disable, status, or reindex.

```APIDOC
## calibredb fts_index

### Description
Control the Full text search indexing process. The command accepts one of the following subcommands: enable, disable, status, or reindex.

### Method
CLI

### Endpoint
calibredb fts_index [options] enable/disable/status/reindex

### Parameters
#### Subcommands
- **enable** - Turns on FTS indexing for this library.
- **disable** - Turns off FTS indexing for this library.
- **status** - Shows the current indexing status.
- **reindex** - Can be used to re-index either particular books or the entire library. To re-index particular books specify the book ids as additional arguments after the reindex command. If no book ids are specified the entire library is re-indexed.

#### Options
- **--indexing-speed** (string) - Optional - The speed of indexing. Use fast for fast indexing using all your computers resources and slow for less resource intensive indexing. Note that the speed is reset to slow after every invocation.
- **--wait-for-completion** (flag) - Optional - Wait till all books are indexed, showing indexing progress periodically.

### Request Example
calibredb fts_index enable
calibredb fts_index reindex 1 2 3

### Response
#### Success Response
No specific response format documented.
```

--------------------------------

### Remove custom column with calibredb remove_custom_column

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Removes the custom column identified by label. Use --force, -f to skip confirmation. See available columns with the custom_columns command. Enclose arguments with spaces in quotation marks.

```bash
calibredb remove_custom_column [options] label

```

--------------------------------

### calibredb search

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Search the library for the specified search term, returning a comma separated list of book ids matching the search expression.

```APIDOC
## calibredb search

### Description
Search the library for the specified search term, returning a comma separated list of book ids matching the search expression. The output format is useful to feed into other commands that accept a list of ids as input.

### Method
CLI

### Endpoint
calibredb search [options] search expression

### Parameters
#### Options
- **--limit, -l** (integer) - Optional - The maximum number of results to return. Default is all results.

### Request Example
calibredb search author:asimov 'title:"i robot"'

### Response
#### Success Response
Comma separated list of book ids matching the search expression.
```

--------------------------------

### calibredb remove_format

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Removes a specific format from a book in the Calibre database. If the format is not present, the command does nothing.

```APIDOC
## calibredb remove_format

### Description
Remove the format fmt from the logical book identified by id. You can get id by using the search command. fmt should be a file extension like LRF or TXT or EPUB. If the logical book does not have fmt available, do nothing.

### Method
remove_format

### Endpoint
calibredb remove_format [options] id fmt

### Parameters
#### Path Parameters
- **id** (string) - Required - The logical book ID.
- **fmt** (string) - Required - The format to remove, specified as a file extension (e.g., LRF, TXT, EPUB).

### Notes
Whenever you pass arguments to calibredb that have spaces in them, enclose the arguments in quotation marks. For example: "/some path/with spaces".
```

--------------------------------

### calibredb fts_search

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Performs a full text search on the entire library or a subset of it. Supports options for exact word matching, including snippets, setting indexing threshold, customizing snippet markers, output format, and restricting the search scope.

```APIDOC
## calibredb fts_search

### Description
Do a full text search on the entire library or a subset of it.

### Usage
calibredb fts_search [options] search expression

### Options
- **--do-not-match-on-related-words** - Only match on exact words not related words. So correction will not match correcting.
- **--include-snippets** - Include snippets of the text surrounding each match. Note that this makes searching much slower.
- **--indexing-threshold** - How much of the library must be indexed before searching is allowed, as a percentage. Defaults to 90.
- **--match-end-marker** - The marker used to indicate the end of a matched word inside a snippet.
- **--match-start-marker** - The marker used to indicate the start of a matched word inside a snippet.
- **--output-format** - The format to output the search results in. Either "text" for plain text or "json" for JSON output.
- **--restrict-to** - Restrict the searched books, either using a search expression or ids. For example: ids:1,2,3 to restrict by ids or search:tag:foo to restrict to books having the tag foo.

### Notes
Whenever you pass arguments to calibredb that have spaces in them, enclose the arguments in quotation marks. For example: "/some path/with spaces".
```

--------------------------------

### calibredb embed_metadata

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Update metadata in the actual book files from the calibre database. Use the --only-formats option to limit updates to specific formats.

```APIDOC
## embed_metadata

### Description
Update the metadata in the actual book files stored in the calibre library from the metadata in the calibre database. This is useful if you want the files to be updated in place.

### Method
calibredb embed_metadata

### Endpoint
calibredb embed_metadata [options] book_id

### Parameters
#### Arguments
- **book_id** (string) - Required - The ID of the book to update. Use 'all' to update all books. You can also specify many book ids separated by spaces and id ranges separated by hyphens. For example: 1 2 10-15 23

#### Options
- **--only-formats, -f** (string) - Optional - Only update metadata in files of the specified format. Specify it multiple times for multiple formats. By default, all formats are updated.

### Notes
Whenever you pass arguments to calibredb that have spaces in them, enclose the arguments in quotation marks. For example: "/some path/with spaces"
```

--------------------------------

### calibredb remove_custom_column

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Removes a custom column identified by its label. Requires confirmation unless the --force option is used.

```APIDOC
## calibredb remove_custom_column

### Description
Remove the custom column identified by label. You can see available columns with the custom_columns command.

### Method
CLI

### Endpoint
calibredb remove_custom_column [options] label

### Parameters
#### Options
- **--force, -f** - Optional - Do not ask for confirmation.

#### Arguments
- **label** - Required - The label of the custom column to remove.

### Notes
Whenever you pass arguments to calibredb that have spaces in them, enclose the arguments in quotation marks. For example: "/some path/with spaces"
```

--------------------------------

### calibredb remove

Source: https://manual.calibre-ebook.com/generated/en/calibredb.html

Removes books from the Calibre database by their IDs. Supports comma-separated lists and ranges, with an option to permanently delete without using the Recycle Bin.

```APIDOC
## calibredb remove

### Description
Remove the books identified by ids from the database. ids should be a comma separated list of id numbers (you can get id numbers by using the search command). For example, 23,34,57-85 (when specifying a range, the last number in the range is not included).

### Method
remove

### Endpoint
calibredb remove ids

### Parameters
#### Path Parameters
- **ids** (string) - Required - Comma separated list of id numbers, e.g., 23,34,57-85. Ranges are supported; the last number in a range is not included.

#### Options
- **--permanent** (flag) - Optional - Do not use the Recycle Bin.

### Notes
Whenever you pass arguments to calibredb that have spaces in them, enclose the arguments in quotation marks. For example: "/some path/with spaces".
```
Tokens:
Raw