Installation

Quick Install (TUI)

For the terminal version on macOS and Linux, run this in your terminal:

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

This automatically detects your operating system and architecture, downloads the TUI binary, and installs it to ~/.local/bin/strayfiles.

Note: You may need to add ~/.local/bin to your PATH if it isn’t already. Add this to your shell profile (.bashrc, .zshrc, etc.):

export PATH="$HOME/.local/bin:$PATH"

Manual Download

Download the latest version from our download page.

Platforms

Platform	Type	Architectures	Requirements
macOS	TUI (terminal)	Intel (x64), Apple Silicon (arm64)	macOS 13.0 or later
Linux	TUI (terminal)	x64, arm64	64-bit Linux
iOS	Native app (Pro, cloud-only)	—	iOS 26.0+, Pro subscription

First Launch

After installing, launch the TUI by running strayfiles in your terminal. To start tracking your Markdown files:

1. Open file discovery — Press / to open the file discovery panel
2. Navigate to your project — Browse to the directory containing your Markdown files
3. Find Markdown files — strayfiles will scan the directory and show available .md files
4. Choose a tracking method — Select how to track each file:
   • Frontmatter [i] — Injects a UUID into YAML frontmatter (survives renames)
   • HTML Comment [h] — Adds a hidden UUID comment (ideal for READMEs)
   • User TOML [t] — Adds the path to ~/.strayfiles/strayfiles.toml
   • Project TOML [p] — Adds the path to the project’s strayfiles.toml

Once files are tracked, they appear in the note tree and are ready to browse and edit.

Creating Your First Note

To create a new note in strayfiles:

1. Select a directory in the note tree
2. Press m to open the actions menu
3. Select “Add note”
4. Enter a name for your note

Important: The note is created in the currently selected directory. strayfiles creates an actual Markdown file at that location, not in a database.

This means:

• Your notes are always accessible as regular .md files
• You can edit them with any text editor
• They work with Git, iCloud, Dropbox, or any sync tool
• If you delete the note in strayfiles, the file is also deleted (see File Deletion Behavior)

Adding Existing Files

Already have Markdown files? You don’t need to create new notes. Instead:

1. Add frontmatter to your existing files (see Frontmatter Basics)
2. Or configure folders in strayfiles.toml (see TOML Config)

strayfiles will index them without moving or copying anything.