FsPulse

FsPulse is a Rust-based tool that captures and analyzes the state of directories over time. It runs as a web service with browser-based interface, or as a traditional command-line tool. Track changes, validate file integrity, and query results with a powerful SQL-like syntax.

🐳 Quick Start with Docker

docker run -d \
  --name fspulse \
  -p 8080:8080 \
  -v fspulse-data:/data \
  -v ~/Documents:/roots/documents:ro \
  gtunesdev/fspulse:latest

Access the web UI at http://localhost:8080

See the Docker Deployment Guide for complete documentation.

🚀 Key Capabilities

• Web UI & Background Service — Run as a daemon with browser-based access to all features
• Command-Line Interface — Full CLI with interactive TUI modes for terminal users
• Directory Scanning — Track file and folder additions, deletions, and modifications
• Content Validation — Validate file types such as FLAC, JPEG, PNG, GIF, BMP, and PDF
• SHA2 Hashing — Optionally detect content changes beyond metadata
• Powerful Querying — SQL-inspired query language for flexible results
• Docker Deployment — Official multi-architecture images (amd64, arm64)

📚 Documentation

Full user guide is available here:

👉 FsPulse Documentation

Key sections:

• Getting Started
• Query Syntax
• Command-Line Interface
• Interactive Mode
• Scanning
• Validators
• Configuration

🛠 Building from Source

git clone https://github.com/gtunes-dev/fspulse.git
cd fspulse
cargo build --release

Run from the target/release directory:

./target/release/fspulse --help

⚡ Quick Examples

Run a scan:

fspulse scan --root-path /some/directory

Launch interactive mode:

fspulse interact

Use query syntax to explore results:

fspulse query "items where item_path:('reports')"

fspulse query "changes where val_new:(I) show default, val_old, val_new order by change_id desc"

🤝 Contributions

FsPulse is under active development, but is not currently accepting external contributions. This may change in the future — see our Development Guide for details.

📄 License

Released under the MIT License. See LICENSE for details.