librius 0.2.4

A personal library manager CLI written in Rust.
Documentation

📚 Librius

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

  • Backup command (librius backup)

    • Creates plain .sqlite backups in the backups/ directory
    • Optional --compress flag for compressed backups
      • .zip format on Windows
      • .tar.gz format on macOS and Linux
    • Localized help and messages via i18n (English and Italian)
    • Timestamp-based file naming for safe sequential backups

  • Export command (librius export)

    • Added support for exporting library data in multiple formats:
      • --csv (default): plain text export with semicolon delimiter
      • --json: structured JSON array output
      • --xlsx: formatted Excel file using umya-spreadsheet
    • Localized CLI help and status messages (English/Italian)
    • Automatic export directory and timestamped filenames
    • Uses dirs crate for cross-platform export path handling

  • Import command (librius import)

    • Supports importing book data from external sources
    • Available formats:
      • --csv (default): semicolon-delimited CSV
      • --json: JSON array of objects
    • Unified parsing via serde and shared BookRecord struct
    • Duplicate detection through unique index on isbn
    • Uses INSERT OR IGNORE for idempotent imports (no duplication)
    • Verbose mode logs skipped records (e.g., “Skipped duplicate ISBN: …”)
    • Non-blocking import completion logging

📦 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

Status Feature Description
✅ List Display all books stored in the local database
✅ Config management Manage YAML config via config --print, --init, --edit, and --editor
✅ Backup Create plain or compressed database backups (.sqlite, .zip, .tar.gz)
✅ Export Export data in CSV, JSON, or XLSX format
✅ Import Import data from CSV or JSON files (duplicate-safe via ISBN)
✅ Database migrations Automatic schema upgrades at startup
✅ Logging system Records operations and migrations in log table
✅ Verbose mode Optional --verbose flag for detailed debug output
✅ Safe patch system Each migration is idempotent and logged for traceability
✅ Multilanguage (i18n) Localized CLI (commands, help); embedded JSON; --lang + YAML language
🚧 Add / Remove Add or delete books via CLI commands
🚧 Search Search by title, author, or ISBN
🚧 Export / Import Export and import data (JSON, CSV)

🌍 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)]);

🧾 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

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