Marlin Demo 🚀

Below is a “hello-world” walk-through that matches the current main branch (auto-scan on marlin init, no more forced-migration chatter, cleaner build). Everything runs offline on a throw-away directory under ~/marlin_demo.

0 Build & install Marlin

# inside the repo
export CARGO_TARGET_DIR=target      # <-- speeds up future builds (once)
cargo build --release               # build the new binary
sudo install -Dm755 target/release/marlin /usr/local/bin/marlin
#   (cargo install --path . --locked --force  works too)

1 Create the demo tree

rm -rf ~/marlin_demo
mkdir -p ~/marlin_demo/{Projects/{Alpha,Beta,Gamma},Logs,Reports,Scripts,Media/Photos}
# (zsh users: quote the pattern or enable braceexpand first)

# ── Projects ───────────────────────────────────────────────────
cat <<EOF > ~/marlin_demo/Projects/Alpha/draft1.md
# Alpha draft 1
- [ ] TODO: outline architecture
- [ ] TODO: write tests
EOF
cat <<EOF > ~/marlin_demo/Projects/Alpha/draft2.md
# Alpha draft 2
- [x] TODO: outline architecture
- [ ] TODO: implement feature X
EOF
cat <<EOF > ~/marlin_demo/Projects/Beta/notes.md
Beta meeting notes:

- decided on roadmap
- ACTION: follow-up with design team
EOF
cat <<EOF > ~/marlin_demo/Projects/Beta/final.md
# Beta Final
All tasks complete. Ready to ship!
EOF
cat <<EOF > ~/marlin_demo/Projects/Gamma/TODO.txt
Gamma tasks:
TODO: refactor module Y
EOF

# ── Logs & Reports ─────────────────────────────────────────────
echo "2025-05-15 12:00:00 INFO  Starting app"  >  ~/marlin_demo/Logs/app.log
echo "2025-05-15 12:01:00 ERROR Oops, crash"   >> ~/marlin_demo/Logs/app.log
echo "2025-05-15 00:00:00 INFO  System check OK" > ~/marlin_demo/Logs/system.log
printf "Q1 financials\n" > ~/marlin_demo/Reports/Q1_report.pdf

# ── Scripts & Media ────────────────────────────────────────────
cat <<'EOF' > ~/marlin_demo/Scripts/deploy.sh
#!/usr/bin/env bash
echo "Deploying version $1…"
EOF
chmod +x ~/marlin_demo/Scripts/deploy.sh
echo "JPEGDATA" > ~/marlin_demo/Media/Photos/event.jpg

2 Initialise and index (one step)

cd ~/marlin_demo          # run init from the folder you want indexed
marlin init               # • creates or migrates DB
                          # • runs *first* full scan of this directory

Add more directories later with marlin scan <dir>.

3 Tagging examples

# Tag all project markdown as ‘project/md’
marlin tag '~/marlin_demo/Projects/**/*.md' project/md

# Tag your logs
marlin tag '~/marlin_demo/Logs/**/*.log' logs/app

# Tag everything under Beta as ‘project/beta’
marlin tag '~/marlin_demo/Projects/Beta/**/*' project/beta

4 Set custom attributes

marlin attr set '~/marlin_demo/Projects/Beta/final.md' status  complete
marlin attr set '~/marlin_demo/Reports/*.pdf'          reviewed yes

5 Play with search / exec hooks

marlin search TODO
marlin search tag:project/md
# Content search arrives in Phase 3. For now, grep the logs directly:
# marlin search 'tag:logs/app AND ERROR'
grep ERROR ~/marlin_demo/Logs/app.log
marlin search 'attr:status=complete'
marlin search 'attr:reviewed=yes AND pdf'
marlin search 'attr:reviewed=yes' --exec 'xdg-open {}'
marlin --format=json search 'attr:status=complete'     # machine-readable output

6 Verbose mode

marlin --verbose scan ~/marlin_demo     # watch debug logs stream by

7 Snapshot & restore

snap=$(marlin backup | awk '{print $NF}')
rm ~/.local/share/marlin/index.db       # simulate disaster
marlin restore "$snap"
marlin search TODO                      # still works

(Reminder: Marlin also makes an auto-backup before every non-init command, so manual snapshots are extra insurance.)

8 Linking demo

touch ~/marlin_demo/foo.txt ~/marlin_demo/bar.txt
marlin scan ~/marlin_demo                        # index the new files

foo=~/marlin_demo/foo.txt
bar=~/marlin_demo/bar.txt

marlin link add "$foo" "$bar" --type references  # create typed link
marlin link list "$foo"                          # outgoing links from foo
marlin link backlinks "$bar"                     # incoming links to bar

9 Collections & smart views

# Collection
marlin coll create SetA
marlin coll add    SetA '~/marlin_demo/Projects/**/*.md'
marlin coll list   SetA

# Saved view (smart folder)
marlin view save tasks 'attr:status=complete OR TODO'
marlin view exec tasks

Recap

cargo build --release + sudo install … is still the build path.
marlin init scans the current working directory on first run.
Scan again only when you add new directories (marlin scan …).
Auto-backups happen before every command; manual marlin backup gives you extra restore points.

Happy organising!

5.1 KiB Raw Permalink Blame History Unescape Escape