Marlin

Marlin is a lightweight, metadata-driven file indexer that runs entirely on your computer. It scans folders, stores paths and file stats in SQLite, lets you add hierarchical tags and custom attributes, takes automatic snapshots, and offers instant full-text search with FTS5. Nothing ever leaves your machine.

---

Feature highlights

Area	What you get
Safety	Timestamped backups marlin backup and one-command restore marlin restore
Upgrades	Automatic schema migrations + dynamic column adds
Indexing	Fast multi-path scanner (WAL mode)
Metadata	Hierarchical tags (project/alpha) & key-value attributes (reviewed=yes)
Search	Prefix-aware FTS5, optional --exec action per hit
DX / Logs	Readable tracing (RUST_LOG=debug …)

---

How it works

┌──────────────┐  marlin scan          ┌─────────────┐
│  your files  │ ─────────────────────▶│   SQLite    │
│ (any folder) │                      │  files/tags │
└──────────────┘   tag / attr          │ attrs / FTS │
        ▲  search / exec              └──────┬──────┘
        └────────── backup / restore          ▼
                                     timestamped snapshots

---

Prerequisites

Requirement	Why
Rust ≥ 1.77	Build toolchain (rustup.rs)
C build essentials	gcc, make, etc. for bundled SQLite

(Windows/macOS: let the Rust installer pull the matching build tools.)

---

Build & install

git clone https://github.com/yourname/marlin.git
cd marlin
cargo build --release
# optional: add to PATH
sudo install -Dm755 target/release/marlin /usr/local/bin/marlin

---

Quick start

marlin init                                        # create DB
marlin scan ~/Pictures ~/Documents                 # index files
marlin tag  "~/Pictures/**/*.jpg" photos/trip-2024 # add tag
marlin attr set "~/Documents/**/*.pdf" reviewed yes
marlin search reviewed --exec "xdg-open {}"        # open hits
marlin backup                                      # snapshot DB

Database location

• Linux ~/.local/share/marlin/index.db
• macOS ~/Library/Application Support/marlin/index.db
• Windows %APPDATA%\marlin\index.db

Override:

export MARLIN_DB_PATH=/path/to/custom.db

---

CLI reference

marlin <COMMAND> [ARGS]

init                             create / migrate database
scan   <PATHS>...                walk directories & index files
tag    "<glob>" <tag_path>       add hierarchical tag
attr   set|ls …                  manage custom attributes
search <query> [--exec CMD]      FTS query, optionally run CMD on each hit
backup                           create timestamped snapshot in backups/
restore <snapshot.db>            replace DB with snapshot

Attribute subcommands

Command	Example
attr set	marlin attr set "~/Docs/**/*.pdf" reviewed yes
attr ls	marlin attr ls ~/Docs/report.pdf

---

Backups & restore

• Create snapshot

  marlin backup
  # → ~/.local/share/marlin/backups/backup_2025-05-14_22-15-30.db
  

• Restore snapshot

  marlin restore ~/.local/share/marlin/backups/backup_2025-05-14_22-15-30.db
  

Marlin automatically takes a safety backup before any schema migration.

---

Upgrading to a new build

cargo install --path . --force    # rebuild & overwrite installed binary

Backups + dynamic migrations mean your data is preserved across upgrades.

---

Roadmap

Milestone	Focus
M1	tags:// virtual folder • attribute search DSL
M2	Real-time sync service • change-log diff viewer
M3	Natural-language query builder
M4	Plug-in marketplace • mobile (read-only) companion

---

Five-minute tutorial

# 0. Playground
mkdir -p ~/marlin_demo/{Projects/{Alpha,Beta},Media/Photos,Docs}
echo "Alpha draft"  > ~/marlin_demo/Projects/Alpha/draft.txt
echo "Receipt PDF"  > ~/marlin_demo/Docs/receipt.pdf
echo "fake jpg"     > ~/marlin_demo/Media/Photos/vacation.jpg

# 1. Init & scan
marlin init
marlin scan ~/marlin_demo

# 2. Tags & attributes
marlin tag  "~/marlin_demo/Projects/Alpha/**/*"  project/alpha
marlin attr set "~/marlin_demo/**/*.pdf" reviewed yes

# 3. Search
marlin search alpha
marlin search reviewed --exec "echo Found: {}"

# 4. Snapshot & restore
marlin backup
marlin restore ~/.local/share/marlin/backups/backup_YYYY-MM-DD_HH-MM-SS.db

---

License

MIT – see LICENSE