NAME

gutenberg - Fetch ebooks from Project Gutenberg

SYMOPSIS

gutenberg [options] command [command options] [args]

DESCRIPTION

gutenberg is a utility that provides a command-line interface for fetching ebook files from Project Gutenberg, a project dedicated to cataloging and archiving public-domain ebooks.

gutenberg performs operations by being given commands. A list of commands is documented in the "COMMANDS" section of this manual.

COMMANDS

update

Downloads a local copy of the Project Gutenberg catalog file, storing it as pg_catalog.csv in gutenberg's data directory. A copy of the catalog file is required before gutenberg can perform any other operation.

This command should be ran periodically, so that gutenberg can be informed of any new ebooks and modified ebook metadata.

This command does not have any unique options.

get target

Downloads an ebook file that matches target. target can be one of the following:

ID

If target is numerical, gutenberg will interpret it as an ID and download the specific ebook that corresponds to that ID.

title regex

If target starts and ends with a slash ('/') character, gutenberg will interpret it as a Perl regex and present the user with a list of ebooks to download whose titles match the given regex (case-insensitive).

title string

If target does not look like an ID or regex, gutenberg will interpret it as just a string and present the user with a list of ebooks to download whose titles contain the given string (case-insensitive).

When multiple ebooks match the given target, gutenberg will present the user with the list of matching ebooks and prompt them for which one to download.

title is optional when using one or more of the -a|--author, -s|--subject, -l|--language, and -H|--shelf options.

get has the following options:

-t|--to=path

Download ebook to path. If path ends with the '.*' suffix, the '.*' will be substituted with the file suffix used by the ebook's format. By default, gutenberg will download the ebook to id.*.

-f|--format=format

Specify what ebook format to download. format can be one of the following (case does not matter):

html

Single HTML page.

epub3

Newer style EPUB. May not be compatible with older e-readers.

epub

Older stlye EPUB. Better compatibility with older e-readers.

epub-noimages

Same as epub but with no images.

kindle

KF8 ebook, an Amazon-proprietary ebook format used by newer Kindle devices.

mobi

Ebook format commonly used by older Kindle devices.

text

Plain text file.

zip

Zip archive of HTML and images.

get uses epub3 by default.

-a|--author=author

Look for ebooks written by specified authors. How this option works is that gutenberg will split the given author string into a list of words and find ebooks that contain each word in their author entries. For example:

# gutenberg will search for ebooks whose author lists contain the names
# 'Herman' and 'Melville'
gutenberg get -a 'Herman Melville'

This option can be used multiple times to specify multiple different authors.

-s|--subject=subject

Look for ebooks categorized under specified subjects. This option works similarly to the -a|--author option.

This option can be used multiple times to specify multiple different subjects.

-l|--language=lang

Look for ebooks under the language lang. lang must be a two-character language code.

-H|--shelf=shelf

Look for ebooks categorized under specified shelves. This option works similarly to the -a|--author option.

This option can be used multiple times to specify multiple different shelves.

search target

Searches for a list of ebooks that match target. The same rules get uses for interpretting target are used by search.

search has the following options:

-a|--author=author

-s|--subject=subject

-l|--language=lang

-H|--shelf=shelf

These options work the same as their get counterparts. When using one or more of these options, target is optional.

meta id

Prints the metadata for the ebook corresponding to id.

meta has the following options:

-j|--json

Print ebook metadata in JSON.

OPTIONS

These options are applicable to every command.

-d|--data=dir

Specify directory to store gutenberg data files in. Can also be configured via the GUTENBERG_DATA environment variable. Defaults to ~/.gutenberg.

-y|--no-prompt

Disable prompts for user input. Yes or no prompts are automatically answered yes to. Prompts asking for the user to select an item from a list will automatically be answered with the first item in the list. This option can be combined with the -q|--quiet option to disable all non-essential output.

-q|--quiet

Disbale informative output.

-h|--help

Display gutenberg manual.

-v|--version

Print gutenberg version/copyright information and exit.

ENVIRONMENT

GUTENBERG_DATA

Directory to store gutenberg data files in.

CAVEATS

This utility is NOT designed for scraping or bulk downloading files from Project Gutenberg. Attempting to use this utility to do so may result in Project Gutenberg banning you from using their site. You have been warned.

RESTRICTIONS

This program does not currently support fetching non-text ebooks, like audio books. Support for non-text formats may be added in the future, if there is enough demand.

AUTHOR

Written by Samuel Young, <samyoung12788@gmail.com>.

This project's source can be found on its Codeberg page. Comments and pull requests are welcome!

COPYRIGHT

Copyright (C) 2025 Samuel Young

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.