Skip to content

Access & Speed on macOS 27#

fn works on macOS 27 whether or not you change any settings. This page explains the note it sometimes prints, and how to make queries faster.

The note you might see#

Note: fn read your note files directly, because macOS doesn't allow Terminal to open FoldNotes' index.
  Faster: System Settings ▸ Privacy & Security ▸ Files & Folders ▸ Terminal ▸ turn on FoldNotes.
  How: https://docs.foldnotes.io/cli/permissions/   (--quiet hides this note)

The command still did what you asked. The note only tells you it took the slower path.

Why it happens#

FoldNotes keeps an index of your notes (tags, tasks, backlinks) so it can answer questions instantly. That index lives in FoldNotes' private storage on your Mac.

On macOS 27, an app made by another developer can only read another app's private storage if you allow it. When you run fn, macOS checks the app you ran it from, such as Terminal, iTerm, Visual Studio Code or Claude, not fn itself. Until you allow that app, macOS refuses quietly, without showing a prompt.

When that happens, fn builds its own index from your note files instead. Your notes are in your collection folder, not in FoldNotes' private storage, so fn can always read them.

What changes and what doesn't#

Without access With access
Every command works ✓ ✓
Results are correct and current ✓ ✓
Creating and editing notes and tasks ✓ ✓
Speed of tag, task, backlink and search queries A second or two for a few hundred notes Instant
Note printed on each command Yes, unless you pass --quiet No
Choosing a collection by name, e.g. --collection "Research" Use the folder path instead ✓

Opening FoldNotes doesn't change any of this. Access depends only on the app you run fn from.

Turn on the faster way#

  1. Open System Settings ▸ Privacy & Security ▸ Files & Folders.
  2. Find the app you run fn from, e.g. Terminal.
  3. Turn on FoldNotes under it.

That's it. The next fn command reads FoldNotes' index directly.

One setting per app, not per window. Allowing Terminal covers every Terminal window and tab, every shell and every script run there, and it stays on after restarts. Each different app you run fn from needs its own setting:

  • other terminal apps, such as iTerm2, Ghostty or Warp
  • editors with a built-in terminal, such as Visual Studio Code or Cursor
  • AI apps that run fn for you, such as Claude with the FoldNotes MCP server
  • automation apps that run shell commands, such as Keyboard Maestro

Not sure which app to allow?

Run fn collection doctor. The Launched from line names the app macOS checks.

No app to allow

Commands run over SSH, or from cron or launchd, have no app to allow in Files & Folders. They always use the file index, which works the same way, just a little slower.

Hide the note#

Pass --quiet to any command. The note goes to standard error, never standard output, so it never mixes into --json results or text a script reads.

Choosing a collection without access#

Without access, fn can't read FoldNotes' list of collections, so a collection name or UUID can't be looked up. Pass the folder path instead:

fn tasks --overdue --collection ~/Library/Mobile\ Documents/iCloud~com~foldnotes/Documents

Your default collection still works. So does a collection chosen with fn collection switch, because fn remembers its folder. If you switched before updating FoldNotes, run fn collection switch once more while you have access, or pass the path.

Check what's happening#

fn collection doctor

The Cache section shows whether fn is reading FoldNotes' index or one built from your note files, and why.