librius 0.5.0

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.0

🧪 Complete test suite

Introduced a robust automated testing framework for both CLI and database layers.
Tests now use the real production schema, ensuring consistent validation of all database operations.
Added a new helper setup_temp_db() that automatically creates temporary SQLite databases:
- Windows → %TEMP%\librius_test_*.db
- macOS / Linux → /tmp/librius_test_*.db
Unified test structure under /tests/ for clarity and scalability.

Example structure:

tests/
├── common.rs # Shared helpers (DB setup, fixtures)
├── db_tests.rs # Database-level tests
├── cli_tests.rs # CLI behavior tests
├── isbn_tests.rs # ISBN module tests
└── librius_core_tests.rs # Core command handler tests

🔧 Modular CLI refactor

Reorganized the CLI into a modular structure for better readability and future reuse:
- cli/args.rs → Command definitions and global options.
- cli/dispatch.rs → Command routing and subcommand handling.
- cli/mod.rs → Unified CLI interface for main.rs.
Simplified the main dispatcher logic and improved localization consistency.
Prepared the CLI subsystem for integration with the upcoming librius_core library and GUI frontend.

🧱 Internal improvements

Removed legacy #[cfg(test)] blocks from source code.
Cleaned up all build and Clippy warnings.
Verified stability across all major platforms (Windows, macOS, Linux).
Established the technical foundation for continuous integration (coming in v0.5.1).

📦 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`
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]

Options:

--short Compact view
--id Show book by ID
--details Show extended metadata

🔍 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

💾 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!

🧾 Overview

✨ New in v0.5.0

📦 Installation

🐧 AUR (Arch Linux)

🍺 Homebrew (macOS/Linux)

🦀 Crates.io (Rust)

⚙️ Features

📖 Commands Overview

📘 list

🔍 search

➕ add book

✏️ edit book

❌ delete book

⚙️ config

💾 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

Example config (`librius.conf`)

Example table `log`