Command Line Tool (`fn`)¶

FoldNotes includes a command-line tool for creating, reading, updating, and querying notes from the terminal. It operates directly on the same .md files in your collection — no IPC or running app required.

Platform: macOS only.

Installation¶

In FoldNotes: FoldNotes menu > Install Command Line Tool...

The app will show a Terminal command to copy and paste — run it in Terminal to create the symlink. This extra step is required because FoldNotes is sandboxed and cannot write to /usr/local/bin/ directly.

After running the command, fn is available system-wide.

Keep FoldNotes running for best results

Commands that query metadata (tasks, tags, backlinks) read from the app's local cache. FoldNotes updates this cache in real time as iCloud sync events arrive, so the app should be running for the CLI to reflect the latest changes from other devices.

Quick Examples¶

fn list                                    # List all notes
fn create "Meeting Notes"                  # Create a new note
fn show "Meeting Notes"                    # Display a note
fn daily append "Met with Sarah at 3pm"    # Append to today's daily note
fn tasks --overdue                         # Show overdue tasks
fn search "project plan"                   # Full-text search
fn open "Meeting Notes"                    # Open in FoldNotes app
fn collection switch "Work"                # Switch to another collection
fn --collection "Research" list            # Query a different collection

Global Options¶

Every command accepts:

Option	Description
`--collection <ref>`	Override collection by name, UUID, or path. Default: auto-detects active collection from registry, then iCloud Drive, then `~/Documents/FoldNotes/`
`--json`	Output structured JSON instead of human-readable text
`--quiet`	Suppress informational messages (errors still print to stderr)
`--version`	Show version number
`-h, --help`	Show help for any command

Commands¶

See Command Reference for the full list of commands with all options and examples.

How It Works¶

Files are the source of truth. The CLI reads and writes .md files directly.
Read cache, write files. Structured queries (tags, tasks, backlinks) use the app's SwiftData cache for speed. All writes go through the filesystem.
No IPC required. FoldNotes detects file changes automatically and updates its index. The CLI is just another "device" from the app's perspective.
Cache freshness. The app updates the cache in real time as iCloud sync events arrive. For the CLI to reflect the latest changes from other devices, the app should be running. If the app has been closed, the cache will catch up on next launch.
Cache fallback. When the cache is unavailable (app never launched), most commands fall back to file scanning. Commands needing rich metadata (tasks, backlinks) will prompt you to launch FoldNotes once.

Multi-Collection Support¶

The --collection flag resolves by name, UUID, or filesystem path:

fn --collection "Research" list           # list notes in Research
fn --collection "Research" tasks --due-today
fn --collection ~/Documents/Work search "meeting"

Manage collections directly:

fn collection info                        # show active collection
fn collection switch "Work"               # switch active collection
fn collection add ~/Notes --name "Notes"  # register a new collection
fn collection remove "Old" --confirm "Old"  # unregister (files kept)

Automation¶

The CLI works with any automation tool: shell scripts, cron jobs, Python, Raycast, Apple Shortcuts, and more. See Shortcuts & Automation for examples.

For planned AI integration via MCP or Ollama, see AI & Automation.

Command Line Tool (fn)¶