librius 0.4.0

A personal library manager CLI written in Rust.
Documentation

Build Status Docs.rs License: MIT Rust Edition

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

🆕 Edit command

  • New command edit book:
    • Allows editing existing records by ID or ISBN.
    • Supports all editable fields:
      title, author, editor, year, language, pages,
      genre, summary, room, shelf, row, position.
    • Automatically converts language codes (e.g., en → English) via lang_code_to_name().
    • Dynamically generates CLI arguments from a single EDITABLE_FIELDS list.
    • Field updates now show old and new values: 
      ✅ Field “year” updated successfully (2018 → 2020).
✅ Field “language” updated successfully (Italian → English).
    • Final summary messages are plural-aware and localized:
      • English → ✅ Book 9788820382698 successfully updated (2 fields modified).
      • Italian → ✅ Libro 9788820382698 aggiornato correttamente (2 campi modificati).

🌍 Internationalized CLI

  • All commands and help messages are fully localized (en / it).
  • Ordered and grouped help output using display_order() and next_help_heading().
  • Dynamic translations for fields, subcommands, and error messages.

📗 Improved structure

  • Modular command layout (add, edit, list, import, export, backup, config).
  • Centralized field definitions in fields.rs for consistent behavior.
  • Cleaner cli.rs with display order and grouped help sections.

📦 Installation

🐧 AUR (Arch Linux)

AUR

yay -S librius
# or
paru -S librius

🍺 Homebrew (macOS/Linux)

Homebrew Version

brew tap umpire274/tap
brew install librius

🦀 Crates.io (Rust)

Crates.io

cargo install rtimelogger

⚙️ Features

Feature Command Description
List librius list Display all books stored in the local database, in full or compact view
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
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
Dynamic help system librius help <command> Ordered and grouped help output using display_order() and next_help_heading()

💻 Usage

librius list          # Full detailed list
librius list --short  # Compact list (ID, Title, Author, Editor, Year)

🧱 Example output

$ librius list --short

📚  Personal Library
════════════════════════════════════════════════════════════════════════════════

┌────┬──────────────────────────────┬────────────────────┬──────────────┬──────┐
│ ID │ Title                        │ Author             │ Editor       │ Year │
├────┼──────────────────────────────┼────────────────────┼──────────────┼──────┤
│ 1  │ The Rust Programming Language│ Steve Klabnik      │ No Starch    │ 2018 │
│ 2  │ Clean Code                   │ Robert C. Martin   │ Pearson      │ 2008 │
└────┴──────────────────────────────┴────────────────────┴──────────────┴──────┘


# ➕ Add a book automatically by ISBN
$ librius add book --isbn 9788820382698
📘 Book “La lingua dell'antico Egitto” successfully added.

# ✏️ Edit book details
$ librius edit book 9788820382698 --year 2020
✅ Field “year” updated successfully (2018 → 2020).
✅ Book 9788820382698 successfully updated (1 field modified).

# 🌍 Update language (auto conversion from ISO)
$ librius edit book 9788820382698 --lang_book en
✅ Field “language” updated successfully (Italian → English).

# 📚 List your library (compact view)
$ librius list --short

🌍 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

  1. The Hobbit (J.R.R. Tolkien) [1937]
  2. Foundation (Isaac Asimov) [1951]
  3. 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:

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!