Catho

Catho is a command-line file catalog manager inspired by Robert Vasicek's Cathy project. It allows you to index and search files across different media, volumes, and network locations without having physical access to them.

Features

• Index files from any directory, including external drives and network shares
• Search catalogs locally without needing access to the original media
• SHA-256 hashing for duplicate file detection
• SQLite storage for fast, portable catalog databases
• Pattern matching with wildcards and regex support
• Web UI for browsing catalogs (optional feature)
• Export to JSON for integration with other tools

Installation

From crates.io (recommended)

cargo install catho

With web UI support

cargo install catho --features web

From source

git clone https://github.com/iemejia/catho.git
cd catho
cargo build --release

# Or with web UI:
cargo build --release --features web

The binary will be at target/release/catho.

Usage

Create a catalog

# Index a directory with a catalog name
catho add my-usb-drive /media/usb-drive

# Index without calculating file hashes (faster)
catho add my-backup /backup/folder -H none

List catalogs

# List all catalogs
catho ls

# Show details for a specific catalog
catho ls my-usb-drive

Search for files

# Search for files matching a pattern (supports * wildcard)
catho find "*.mp3"

# Search in specific catalogs
catho find "report*.pdf" my-usb-drive my-backup

# Search using regex
catho find --regex "photo_[0-9]{4}\.jpg"

Update a catalog

# Update an existing catalog (adds new files, removes deleted ones)
catho add my-usb-drive /media/usb-drive --continue

Remove a catalog

catho rm my-old-catalog

Scan for duplicates

# Check if a file exists in any catalog (by hash)
catho scan /path/to/file.txt

# Scan an entire directory
catho scan /path/to/folder

Export catalog

# Export to stdout (JSON)
catho export my-catalog

# Export to file
catho export my-catalog -o catalog.json

Web UI (requires --features web)

# Start web server on default port 8080
catho web

# Use custom port and host
catho web -p 3000 --host 0.0.0.0

Then open http://localhost:8080 in your browser.

Catalog Storage

Catalogs are stored as SQLite databases in a platform-specific config directory:

• Linux: ~/.config/catho/catalogs/
• macOS: ~/Library/Application Support/catho/catalogs/
• Windows: C:\Users\<User>\AppData\Roaming\catho\catalogs\

Each catalog contains:

• File names and paths (relative to the indexed root)
• File sizes and modification dates
• SHA-256 hashes (optional) for duplicate detection

Development

Running tests

cargo test -- --test-threads=1

Building

# Debug build
cargo build

# Release build
cargo build --release

# With web feature
cargo build --release --features web

Linting

cargo clippy
cargo fmt --check

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass and linting is clean
5. Submit a pull request

License

This project is licensed under the GNU Lesser General Public License v3.0 - see the LICENSE file for details.