FanFicFare Documentation

You can install the FanFicFare Command Line Interface (CLI) as a Python package using pip. This is the standard way to use FanFicFare outside of the Calibre plugin environment.

pip install FanFicFare

If you need to test the latest changes before an official release, you can install the test version of the CLI from the testpypi repository.

pip install --extra-index-url https://test.pypi.org/simple/ --upgrade FanFicFare

If you want to provide translations for FanFicFare or other Calibre plugins, you can do so through the Transifex platform. Use the project link below to access the translation interface and contribute your language strings.

https://www.transifex.com/projects/p/calibre-plugins/resources/

To enable support for downloading images within story text (for EPUB and HTML formats), you must install the image_processing extra, which includes the Pillow library.

pip install FanFicFare[image_processing]

FanFicFare loads configuration from multiple sources with a specific priority order. Settings in files with higher priority override those in lower priority files.

Priority Order (Lowest to Highest):

1. defaults.ini (in the FanFicFare directory)
2. defaults.ini in ~/.fanficdownloader/ or ~/.fanficfare/
3. defaults.ini in $XDG_CONFIG_HOME/fanficfare/
4. defaults.ini in the current directory (./)
5. personal.ini in ~/.fanficdownloader/ or ~/.fanficfare/
6. personal.ini in $XDG_CONFIG_HOME/fanficfare/
7. personal.ini in the current directory (./)
8. Files explicitly provided via the -c or --config flag (these take the highest priority).

Note: The CLI also allows overriding any setting via --option NAME=VALUE.

The FanFicFare CLI allows you to download fanfiction stories from various sites into formats like EPUB, MOBI, TXT, or HTML. You can provide a single story URL or a list of URLs from a file.

Basic Usage:

fanficfare [STORYURL]...

Common Tasks:

• Download in a specific format: Use -f or --format (default is epub).
• Download a range of chapters: Use -b or --begin and -e or --end, or append the range to the URL like STORYURL[1-5].
• Update an existing EPUB: Use -u or --update-epub to add new chapters to an existing file.
• Download from a file list: Use -i or --infile to specify a file containing URLs.
• Get metadata only: Use -m or --meta-only to retrieve metadata without downloading chapters.

fanficfare https://example.com/story/123 -f epub

You can override any configuration setting defined in your .ini files using the --option flag. This is useful for one-off changes like setting authentication or behavior without modifying permanent config files.

Format:

--option NAME=VALUE

Example (setting adult check):

fanficfare --option is_adult=true [STORYURL]

Use these flags to inspect stories or extract URLs without performing a full download.

-l, --list URL
      Get list of valid story URLs from page given.
-n, --normalize-list URL
      Get list of valid story URLs from page given, but normalized to standard forms.
--download-list URL
      Download story URLs retrieved from page given.
--imap
      Get list of valid story URLs from unread email from IMAP account configured in ini.
--download-imap
      Download valid story URLs from unread email from IMAP account configured in ini.
-m, --meta-only
      Retrieve and write metadata to stdout without downloading or saving chapters.
-j, --json-meta
      Output metadata as JSON with download, or with --meta-only flag.
--json-meta-file
      Output metadata for each download as JSON to an individual file named by appending ".json" to the output_filename.