Librius

Librius — A fast, minimalist CLI to manage your personal book collection, built in Rust.

🧾 Overview

Librius is a cross-platform command-line tool written in Rust that helps you manage your personal library.
It uses a SQLite database to store your books and a simple YAML configuration file (librius.conf) for flexible setup.

This project aims to provide a clean, modular architecture with future extensions such as search, add/remove commands, and import/export support.

✨ New in v0.5.1

🗄️ Database management command

A brand new db command has been introduced for complete database lifecycle control:

librius db --init

Initializes or resets the current database.

librius db --reset

Alias of --init.

librius db --copy -f|--file <NEW_FILE>

Copies the database defined in your librius.yaml configuration to a new file.

The database path is automatically read from the database: key in the configuration file.

📚 Improved list details view

Added the --compact flag for list --id <ID> --details to hide empty fields in the vertical table.
The --compact flag now requires --details, ensuring consistent CLI behavior.
Fixed table headers that previously displayed String; now they correctly show localized Field / Value columns.
Field order in detailed view now matches the database schema (id → added_at).

🐞 Fixes & improvements

Fixed --copy flag incorrectly requiring a value.
Improved integration between configuration and database operations.
Enhanced localized messages and help text for better clarity.

📦 Installation

🐧 AUR (Arch Linux)

yay -S librius
# or
paru -S librius

🍺 Homebrew (macOS/Linux)

brew tap umpire274/tap
brew install librius

🦀 Crates.io (Rust)

cargo install rtimelogger

⚙️ Features

Feature	Command	Description
List	`librius list`	Display all books stored in the local database, in full or compact view
Search	`librius search <query>`	Full-text search across title, author, editor, genre, and language fields; supports `--short` for compact view
Add book	`librius add book --isbn <ISBN>`	Add new books using ISBN lookup via Google Books API
Edit book	`librius edit book <ID/ISBN>`	Edit existing records by ID or ISBN; dynamic field generation, language conversion, and plural-aware messages
Delete book	`del <ID/ISBN>`	Delete books by ID or ISBN, with interactive confirmation, `--force` flag, and logged deletions
Config management	`librius config`	Manage YAML configuration via `--print`, `--init`, `--edit`, `--editor`
Database management	`librius db`	DB Management via `--init`, `--reset`, `--copy -f\|--file <name new file>`
Backup	`librius backup`	Create plain or compressed database backups (`.sqlite`, `.zip`, `.tar.gz`)
Export	`librius export`	Export data in CSV, JSON, or XLSX format
Import	`librius import`	Import data from CSV or JSON files (duplicate-safe via ISBN)
Database migrations	(automatic)	Automatic schema upgrades and integrity checks at startup
Logging system	(internal)	Records all operations and migrations in an internal log table
Multilanguage (i18n)	`librius --lang <code>`	Fully localized CLI (commands, help, messages); `--lang` flag and config key
Dynamic help system	`librius help <command>`	Ordered and grouped help output using `display_order()` and `next_help_heading()`

📖 Commands Overview

📘 list

List all books or a specific book by ID.

$ librius list [--short] [--id <ID>] [--details] [--compact]

Options:

--short Compact view
--id Show book by ID
--details Show extended metadata (requires --id)
--compact Compact list view (requires --details)
--help Show command help

🔍 search

Search for books by title, author, editor, genre, or language.

$ librius search <query> [--short]

Options:

--short Show compact view (ID, Title, Author, Editor, Year, ISBN)
<query> Search term
--help Show command help

➕ add book

Add a new book using its ISBN.

$ librius add book --isbn <ISBN>

Options:

--isbn <ISBN> ISBN of the book to add
--help Show command help

✏️ edit book

Edit an existing book by ID or ISBN.

$ librius edit book <ID/ISBN> [--title <TITLE>] [--author <AUTHOR>] [--editor <EDITOR>] [--year <YEAR>] [--genre <GENRE>] [--language <LANGUAGE>] [--isbn <ISBN>]

Options:

<ID/ISBN> ID or ISBN of the book to edit
--title <TITLE> New title
--author <AUTHOR> New author
--editor <EDITOR> New editor
--year <YEAR> New publication year
--genre <GENRE> New genre
--language <LANGUAGE> New language
--isbn <ISBN> New ISBN
--help Show command help

❌ delete book

Delete a book by ID or ISBN.

$ librius del <ID/ISBN> [--force]

Options:

<ID/ISBN> ID or ISBN of the book to delete
--force Skip confirmation prompt
--help Show command help

⚙️ config

Manage application configuration.

$ librius config [--print] [--init] [--edit] [--editor <EDITOR>]

Options:

--print Print current configuration
--init Create default config file
--edit Open config file in editor
--editor <EDITOR> Specify editor (default: $EDITOR or nano
--help Show command help

🗄️ Database management

Manage the Librius database lifecycle and backups.

librius db [--init] [--reset] [--copy -f|--file <NEW_FILE>]

Options:

--init Initialize a new database
--reset Reset the database (deletes all data)
--copy -f|--file <NEW_FILE> Copy the database to a new file
--help Show command help

💾 backup

Create a backup of the database.

$ librius backup [--compress]

Options:

--compress Create a compressed backup (.zip or .tar.gz)
--help Show command help

📤 export

Export library data to CSV, JSON, or XLSX.

$ librius export [--csv | --json | --xlsx] [-o|--output <FILE>]

Options:

--csv Export as CSV (default)
--json Export as JSON
--xlsx Export as XLSX
-o, --output <FILE> Specify output file path
--help Show command help

📥 import

Import library data from CSV or JSON.

$ librius import --file <FILE> [--json] [--csv] [-d|--delimiter <CHAR>]

Options:

--file <FILE> Path to input file
--json Specify if the input file is JSON (default is CSV)
--csv Specify if the input file is CSV
-d, --delimiter <CHAR> Specify CSV delimiter (default: ,)
--help Show command help

🧠 Note

Every command is fully localized in english (default) and italian.

🌍 Multilanguage support (i18n)

Librius now supports a multilingual interface.

Source	Description
🇬🇧 en.json	Default English messages
🇮🇹 it.json	Italian translation
📄 README.md	Located in src/i18n/locales/, describes key naming conventions

How it works

On startup, Librius loads the language defined in:
1. CLI argument --lang / -l
2. Configuration file language:
3. Fallback to English (en)
All user-visible messages (print_info, print_err, etc.) are translated dynamically.
Missing keys automatically fall back to their key name or English equivalent.

Example Usage

# Default (English)
librius list

# Force Italian interface
librius --lang it list

Example config (`librius.conf`)

# librius.conf
database: "C:/Users/YourName/AppData/Roaming/librius/librius.sqlite"
language: "it"  # Set default language to Italian

🧩 Translations

All translations are stored in:

src/i18n/locales/
├── en.json
├── it.json
└── README.md

Each .json file contains key–value pairs like:

{
  "app.config.loading": "Loading configuration...",
  "db.init.ok": "Database created successfully.",
  "book.add.ok": "Book '{title}' added successfully!"
}

Variables can be inserted at runtime:

tr_with!("db.path.open_existing", & [("path", & db_path)]);

🧱 Project structure

src/
├─ main.rs
├─ lib.rs
├─ cli.rs
│
├─ commands/
│   ├─ mod.rs
│   ├─ list.rs
│   ├─ backup.rs
│   ├─ config.rs
│   ├─ export.rs
│   └─ import.rs
│
├─ config/
│   ├─ mod.rs
│   ├─ load_config.rs
│   └─ migrate_config.rs
│
├─ db/
│   ├─ mod.rs
│   ├─ load_db.rs
│   └─ migrate_db.rs
│
├─ i18n/
│   ├─ mod.rs
│   ├─ loader.rs
│   └─ locales/
│       ├─ en.json
│       ├─ it.json
│       └─ README.md
│
├─ models/
│   ├─ mod.rs
│   └─ book.rs
│
└─ utils/
    ├─ mod.rs
    └─ table.rs

🧾 Changelog reference

See CHANGELOG.md for a detailed list of changes and updates.

📤 Export & 📥 Import

Librius now supports full data import/export functionality.

Export

You can export your library to multiple formats:

librius export --csv     # CSV (default)
librius export --json    # JSON
librius export --xlsx    # Excel (XLSX)

Exports are automatically saved in your user data directory (e.g. ~/.config/librius/exports or %APPDATA%\librius\exports).

Import

Import books from CSV or JSON files:

librius import --file examples/books.csv
librius import --file examples/books.json --json

Features:

Automatic detection of duplicate records via unique isbn
Skips duplicates gracefully (no interruption)
Transaction-safe import
Verbose mode logs skipped ISBNs

Example output:

📘  Skipped duplicate ISBN: 978-0-345-33968-3
✅ Imported 6 records from CSV file.

🚀 Quick start

1️⃣ Clone the repository

git clone https://github.com/umpire274/librius.git
cd librius

2️⃣ Build and run

cargo build
cargo run -- list

If this is the first launch, Librius will automatically create:

The config file at ~/.config/librius/librius.conf
A SQLite database at ~/.config/librius/librius.sqlite

🧩 Example output

$ librius list

📚 Your Library

The Hobbit (J.R.R. Tolkien) [1937]
Foundation (Isaac Asimov) [1951]
Dune (Frank Herbert) [1965]

⚙️ Configuration

# librius.conf
database: "C:/Users/YourName/AppData/Roaming/librius/librius.sqlite"
language: "en"

Configuration file is automatically migrated if fields are missing or renamed.
Default path:
- macOS/Linux → $HOME/.librius/librius.conf
- Windows → %APPDATA%\Roaming\librius\librius.conf

🧩 Development notes

Librius now follows a standard Rust modular structure:

Each domain (commands, db, config, models, utils, i18n) exposes its API via mod.rs.
Common utilities like build_table() are reused across commands for consistent output.
The lib.rs re-exports all major modules for cleaner imports in main.rs.

Example import

use librius::{build_cli, handle_list, tr};

📚 Documentation

The API and user-facing documentation for Librius is available on docs.rs:

Online: https://docs.rs/librius

To generate and view the documentation locally run:

cargo doc --no-deps --open

This will build the documentation and open it in your default browser.

🧰 Dependencies

clap — Command-line argument parsing
rusqlite — SQLite database integration
serde / serde_json — Serialization/deserialization
serde_yaml — YAML config parsing
umya-spreadsheet — XLSX file creation
csv — CSV import/export
colored — Colored terminal output
chrono — Date and time utilities

🗄️ Database management

Librius automatically verifies and upgrades the SQLite database schema at startup.

The latest migration adds a unique index on isbn to guarantee that duplicate imports are ignored safely.

CREATE UNIQUE INDEX IF NOT EXISTS idx_books_isbn ON books (isbn);

On first launch → creates books table.
On subsequent launches → runs pending migrations silently.
Migration results are recorded in the log table.

Each migration patch (PATCH_001, PATCH_002, …) is applied once and recorded in the internal log table. The process is fully idempotent — no duplicate operations are ever performed.

📘  Applying database patch: PATCH_002
✅  All pending migrations applied.
✅  Database schema is up-to-date.

Example table `log`

id	date	operation	target	message
1	2025-10-13T21:45:12+02:00	DB_CREATED	DB	Created new database
2	2025-10-13T21:45:13+02:00	DB_MIGRATION_OK	DB	Schema updated successfully

🔍 Verbose mode

Run Librius in diagnostic mode to display all internal initialization steps:

librius --verbose list

Output example:

📘  Loading configuration...
📘  Opening existing database at: C:\Users\A.Maestri\AppData\Roaming\librius\librius.db
✅ Database schema is up-to-date.
✅ Configuration verified.

📚 Your Library

In normal mode, only command output is displayed.

🧪 Development

Run in debug mode

cargo run -- list

Run with logging (future)

RUST_LOG=debug cargo run -- add "Neuromancer"

Format and lint

cargo fmt
cargo clippy

🧱 Future roadmap

Add add, remove, and search commands
Export/import JSON and CSV
Add optional TUI (Text UI) with ratatui
Web dashboard sync

🧑‍💻 Author

Umpire274 GitHub: @umpire274

📜 License

This project is licensed under the MIT License — see the LICENSE

⭐ Contribute

Contributions, feature requests, and ideas are welcome! If you’d like to contribute, please open a pull request or start a discussion.

🧡 Support

If you enjoy this project, please ⭐ star the repository — it helps visibility and development motivation!

Name		Name	Last commit message	Last commit date
Latest commit History 98 Commits
.github		.github
res		res
scripts		scripts
src		src
tests		tests
tools		tools
tools_private @ 7f8e961		tools_private @ 7f8e961
.gitignore		.gitignore
.gitmodules		.gitmodules
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
build.rs		build.rs

License

umpire274/librius

Folders and files

Latest commit

History

Repository files navigation

Librius

🧾 Overview

✨ New in v0.5.1

📦 Installation

🐧 AUR (Arch Linux)

🍺 Homebrew (macOS/Linux)

🦀 Crates.io (Rust)

⚙️ Features

📖 Commands Overview

📘 list

🔍 search

➕ add book

✏️ edit book

❌ delete book

⚙️ config

🗄️ Database management

💾 backup

📤 export

📥 import

🧠 Note

🌍 Multilanguage support (i18n)

How it works

Example Usage

Example config (librius.conf)

🧩 Translations

🧱 Project structure

🧾 Changelog reference

📤 Export & 📥 Import

Export

Import

🚀 Quick start

1️⃣ Clone the repository

2️⃣ Build and run

🧩 Example output

⚙️ Configuration

🧩 Development notes

Example import

📚 Documentation

🧰 Dependencies

🗄️ Database management

Example table log

🧪 Development

Run in debug mode

Run with logging (future)

Format and lint

🧱 Future roadmap

🧑‍💻 Author

📜 License

⭐ Contribute

🧡 Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 15

Packages 0

Languages

Example config (`librius.conf`)

Example table `log`

Packages