Skip to content

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 properties list                         # List property definitions
fn properties orphans                      # Find unregistered front matter keys
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> Target a collection by name (or unambiguous name prefix), UUID, or path — resolved against the same collections you see in the app. Default: auto-detects the active collection, 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#

  1. Files are the source of truth. The CLI reads and writes .md files directly.
  2. Read cache, write files. Structured queries (tags, tasks, backlinks) use the app's SwiftData cache for speed. All writes go through the filesystem.
  3. No IPC required. FoldNotes detects file changes automatically and updates its index. The CLI is just another "device" from the app's perspective.
  4. 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.
  5. 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 (or unambiguous prefix), UUID, or filesystem path, and scopes everything that command touches — files, per-collection config (project terminology, property schema, saved queries), and the right per-collection cache:

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

Manage collections directly:

fn collections                            # list all registered collections
fn collection info                        # show the active collection
fn collection switch "Work"               # switch the active collection
fn collection add ~/Notes --name "Notes"  # register a new collection
fn collection remove "Old" --confirm "Old"  # unregister (files kept)
fn collection doctor --collection "Work"  # diagnose how files/config/cache resolve

Diagnosing a mismatch

If a --collection query ever seems to return the wrong data, fn collection doctor prints exactly which folder, config, and cache store that command resolves to.

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.