grawlix/README.md

grawlix

CLI ebook downloader

Supported services

grawlix currently supports downloading from the following sources:

• DC Universe Infinite
• eReolen
• fanfiction.net
• Flipp
• Internet Archive
• Manga Plus
• Marvel Unlimited
• Nextory
• Royal Road
• Saxo
• Storytel / Mofibo
• Webtoons

Installation

From pypi (recommended)

pip install grawlix

From repo (unstable)

git clone https://github.com/jo1gi/grawlix.git
cd grawlix
python3 setup.py install

Authentication

Authentication can either be done with login (username and password) or cookies. Not all sources support both methods.

Login

Some sources require authentication, which can be done either with cli arguments or a config file.

Cli example

grawlix --username "user@example.com" --password "SuperSecretPassword" <url>

Config file example

# Global settings
write_metadata_to_epub = true
output = "~/ebooks/{series}/{index} - {title}.{ext}"

[sources.storytel]
username = "user@example.com"
password = "SuperSecretPassword"

Config file should be placed in:

• Linux: ~/.config/grawlix/grawlix.toml
• macOS: ~/Library/Application Support/grawlix/grawlix.toml
• Windows: %LOCALAPPDATA%\jo1gi\grawlix\grawlix.toml

Cookies

Some sources can be authenticated with Netscape cookie files. I use this extension to export my cookies from my browser.

Cookies can be placed in current dir as cookies.txt or be given with the --cookies argument.

Configuration

Global Settings

The following settings can be added to your config file (before any [sources.*] sections):

Setting	Type	Description	Example
write_metadata_to_epub	boolean	Automatically write metadata to EPUB files (supports Storytel and Nextory)	true or false
output	string	Default output path template (supports ~, environment variables, and template variables)	"~/ebooks/{title}.{ext}"

Output Templates

The output setting supports template variables that are replaced with book metadata:

Variable	Description	Example
{title}	Book title	"The Witcher"
{series}	Series name	"The Witcher Saga"
{index}	Series index/number	"1"
{authors}	Authors (semicolon-separated)	"Andrzej Sapkowski"
{publisher}	Publisher name	"Orbit"
{language}	Language code	"en"
{release_date}	Release date	"2020-01-15"
{source}	Source/service name	"Storytel", "Marvel", etc.
{ext}	File extension (auto-detected from source)	"epub"

Example templates:

# Simple (auto-detect format)
output = "~/books/{title}.{ext}"

# Force EPUB format
output = "~/books/{title}.epub"

# Organized by source
output = "~/books/{source}/{title}.{ext}"

# Organized by series (auto-detect format)
output = "~/books/{series}/{index} - {title}.{ext}"

# Force EPUB with series organization
output = "~/books/{series}/{index} - {title}.epub"

# Organized by source and series
output = "~/books/{source}/{series}/{index} - {title}.epub"

Note: The file extension in your template determines the output format:

• Use .epub to force EPUB output
• Use .cbz to force CBZ (comic book) output
• Use {ext} to auto-detect the best format for each source

Path expansion:

• ~ expands to home directory
• Environment variables work: $HOME (Unix) or %USERPROFILE% (Windows)
• Absolute paths: /path/to/books or C:\Books
• Relative paths: downloads/{title}.{ext} (relative to current directory)

Download books

To download a book run:

grawlix [options] <book url>

Command Line Options

Option	Short	Description
--version	-v	Show version number
--file <path>	-f	File with URLs (one per line)
--username <email>	-u	Username for authentication
--password <password>	-p	Password for authentication
--library <name>		Library name (for sources that require it)
--cookies <path>	-c	Path to Netscape cookie file
--output <template>	-o	Output path template (overrides config)
--write-metadata-to-epub		Write metadata to EPUB files (overrides config)
--debug		Enable debug messages

Examples:

# Download to specific location
grawlix -o "~/downloads/{title}.{ext}" <url>

# Download with metadata writing
grawlix --write-metadata-to-epub <url>

# Batch download from file
grawlix -f urls.txt

# With authentication
grawlix -u user@example.com -p password <url>

# Debug mode
grawlix --debug <url>

Metadata Writing

For supported sources (Storytel and Nextory), grawlix can write rich metadata to EPUB files including:

• Title and original title
• Authors and translators
• Series information (Calibre-compatible)
• Publisher, ISBN, language
• Description and categories/tags
• Release date

Supported Sources

Source	Title	Authors	Translators	Series	Publisher	ISBN	Language	Description	Release Date
Storytel	✓	✓	✓	✓	✓	✓	✓	✓	✓
Nextory	✓	✓	✓	✓	✓	✓	✓	✓	✓

Enable globally in config:

write_metadata_to_epub = true

Or use the CLI flag for one-time use:

grawlix --write-metadata-to-epub <url>