Quick Start

Get Running in 5 Minutes

This guide gets you from zero to your first indexed note in under 5 minutes.

Step 1: Install Strayfiles

CLI / TUI (macOS & Linux):

curl -fsSL https://strayfiles.com/install.sh | sh

macOS App:

Download from our download page
Drag Strayfiles to Applications
Launch from Applications

Step 2: Create Your First Config

Create a strayfiles.toml file in any folder you want to index:

version = 1

[settings]
roots = ["./"]
exclude = ["node_modules/**", ".git/**"]

This tells Strayfiles to index all Markdown files in that folder. By default, every .md file under the configured roots is indexed automatically — no frontmatter required.

Step 3: Add a Note (Optional Frontmatter)

Any Markdown file under your configured roots is automatically indexed. You can optionally add Strayfiles frontmatter to control metadata like workspaces, tags, or an alias:

---
strayfiles:
  enabled: true
  workspaces: ["projects"]
  alias: "My First Note"
---

# My First Note

This note is tracked by Strayfiles!

Frontmatter is only required if you set explicit_only = true in your config — otherwise all Markdown files are picked up without it.

Step 4: Launch the TUI

Run strayfiles in your terminal to open the full terminal UI (TUI) — an interactive, keyboard-driven notes interface, not a CLI that prints output. Your data is stored in ~/.strayfiles/ (including the local database at ~/.strayfiles/data.redb).

Once the TUI is open, press / to open file discovery. This lets you search your filesystem for Markdown files and add them to Strayfiles. You can also point discovery at the folder where your strayfiles.toml lives to pick up everything configured there.

What’s Next?

Core Concepts - Understand how Strayfiles works
Frontmatter Guide - Learn all frontmatter options
TOML Configuration - Advanced config options

Quick Tips

Index existing files without modification:

By default, all Markdown files under your configured roots are indexed automatically — no frontmatter needed. Set explicit_only = true if you want to require frontmatter opt-in:

[settings]
explicit_only = true  # only index files with strayfiles frontmatter
roots = ["./notes", "./docs"]

Use glob patterns:

Target specific files across your filesystem:

[settings]
roots = ["**/CLAUDE.md", "**/README.md"]

Organize with workspaces:

Group notes virtually without moving files:

[workspaces.projects]
include = ["projects/**"]

[workspaces.docs]
include = ["**/docs/**", "**/README.md"]