Linen User Guide
Everything Linen can do — and exactly how to use it. From your first search to the command-line, web, and AI-agent tools.
1 · Install & first launch
Linen is a single notarized, universal app (Apple Silicon & Intel), about 4.5 MB. It lives in your menu bar, not the Dock, and is summoned with a global hotkey.
- Download Linen, open the
.dmg, and drag Linen into your Applications folder. - Launch Linen from Applications. Look for the magnifying-glass icon in your menu bar — it starts indexing your Mac in the background straight away.
- Grant Full Disk Access (recommended) so Linen can index protected places like Mail and Messages: System Settings → Privacy & Security → Full Disk Access → + → Linen. Without it Linen still works, but quietly skips folders macOS protects.
- Press ⌥Space anywhere to open the search panel, and start typing.
2 · The essentials
Linen is keyboard-first, built to feel like Spotlight with a real query language behind it.
- Type to search. Matching files and folders from across your whole startup volume appear the instant you type — names and paths, not a spinner. The top hit is auto-selected.
- Move with ↑ ↓ through the results. Press ↩ (or double-click) to open the selection.
- Right-click a result for Open, Reveal in Finder, Copy Path, and Copy Name.
- Preview with Space. Once you've moved with the arrows, Space opens Quick Look; ⌘Y previews any time. (While you're typing, Space just inserts a space.)
- Sort results by Name, Path, Size, or Date Modified from the footer.
- The menu-bar icon holds the rest: Show Search, Find Duplicate Files, Saved Searches, Rebuild Index, Fast Regex & Similarity, Enter License…, Check for Updates…, and Quit.
3 · Keyboard shortcuts
Everything is reachable without leaving the home row.
| Key | Action |
|---|---|
| ⌥Space | Summon or dismiss the search panel (global, from any app) |
| ↑ ↓ | Move the selection through results |
| ↩ | Open the selected file |
| Space | Quick Look the selection (after moving with the arrows) |
| ⌘Y | Quick Look the selection (any time) |
| ⌘L | Jump back to the search field |
| Esc | Close the preview, or hide the panel |
| Double-click | Open a result |
| Right-click | Open · Reveal in Finder · Copy Path · Copy Name |
In a Quick Look preview, the arrow keys move the selection and the preview follows along, exactly like Finder.
4 · Search syntax
A plain query matches file names. Add operators and filters to be precise — they all combine freely, e.g. image: size:>1mb !screenshot dm:thisyear.
Operators
| Operator | Meaning | Example |
|---|---|---|
| space | AND — all terms must match | report 2024 |
| | OR (binds tighter than AND) | *.jpg|*.png |
! | NOT — exclude | report !draft |
< > | Group terms | !<report 2024> |
" " | Literal text (escape operators) | "final draft" |
Terms & filters
| Type this | To match |
|---|---|
report | Names containing report (case-insensitive) |
*.swift | Wildcards: * = any run, ? = one character |
inv?ice.pdf | invoice.pdf, in0ice.pdf, … |
ext:pdf;txt | Only .pdf or .txt files |
file: · folder: | Files only / folders only |
name:foo | Match the name only |
stem:foo | Match the name without its extension |
path:projects | Match against the full path |
size:>10mb | Size compare — b, kb, mb, gb, tb with < > >= <= = |
dm:today | Modified today (dm: / datemodified:) |
dc:>2024-01-01 | Created after a date (dc: / datecreated:) |
case:Report | Case-sensitive matching |
ww:cat | Whole-word match (ww: / wholeword:) |
regex:^\d{4}- | Regular expression |
File-type macros
Each expands to a curated set of extensions:
| Macro | Matches |
|---|---|
audio: | Music and sound files (mp3, m4a, flac, wav, …) |
video: | Movies (mp4, mov, mkv, avi, …) |
image: | Pictures (jpg, png, heic, gif, raw, …) |
doc: | Documents (pdf, docx, pages, txt, …) |
zip: | Archives (zip, tar, gz, 7z, dmg, …) |
exe: | Apps and binaries |
Combine them with OR, e.g. audio:|video: matches any media file, and image: dm:thisweek finds pictures changed this week.
Dates
Date filters (dm: modified, dc: created) accept named ranges or a comparison:
- Named:
today,yesterday,thisweek/lastweek,thismonth/lastmonth,thisyear/lastyear. - Comparison: against
YYYY,YYYY-MM, orYYYY-MM-DDwith><>=<==— e.g.dm:>=2024-06.
5 · Power features
Beyond exact and boolean matching, Linen adds a smart layer no plain filename search has — all available right in the search panel.
Fuzzy finding, ranked fuzzy:
Subsequence matching with fzf-style relevance — contiguous runs, word-boundary, camelCase, snake_case and path-segment starts rank highest. fuzzy:srcheng finds SearchEngine.swift. Linen also auto-falls back to fuzzy when an exact search finds nothing, and learns the files you open (frecency) to gently boost them.
Similar names similar:
Finds near-duplicate, versioned, or typo variants of a name by trigram overlap — similar:report-final.pdf surfaces report_final_v2.pdf.
Regular expressions regex:
Full regex over names and paths, e.g. regex:^IMG_\d{4}\.HEIC$.
regex: and similar: searches 50–150× faster across a whole-volume index. It uses a little more memory; regex and similarity still work without it, just not as fast.Search inside files content:
Looks for text inside files, not just in their names. Contents are never indexed — Linen reads files on demand, so always pair content: with a fast filter to narrow the candidates first: ext:swift content:NWListener reads only the Swift files. (Aliases: ascii-content:, utf8-content:.)
Finder tags tag:
tag:work finds files with a matching Finder tag; bare tag: matches anything tagged.
Find duplicate files dupe:content
Locates files with identical content (not just identical names) so you can reclaim space, using a progressive size → prefix → suffix → block funnel that stays fast even on multi-gigabyte files. Type dupe:content (combine with any filter, e.g. ext:jpg dupe:content) — or just click Find Duplicate Files in the menu bar. dupe: on its own matches files whose name occurs more than once.
Empty folders empty:
empty: lists folders with no files or subfolders — handy for tidying up.
6 · Saved searches
Name a query once and re-run it whenever you like.
Build a search you'll want again — say ext:mp4 size:>100mb — then save it from the menu bar under Saved Searches → Save Current Search…. Saved searches appear in that submenu for one-click recall, and are shared with the --saved command line. They're stored privately under ~/Library/Application Support/Linen/.
7 · Quick Look
Preview without opening, exactly like Finder.
Move to a result with ↑ ↓ and press Space (or ⌘Y) to preview it. While the preview is open the arrow keys keep moving your selection and the preview follows along; Space toggles it closed again, and ⌘L jumps back to the search field to keep typing.
8 · Your free license
Linen's search is free and needs no key. A free license unlocks the extra tools — and getting one takes a few seconds.
What's free, and what a license unlocks
- Always free, no key: the menu-bar app and ⌥Space search with the entire query language above — wildcards, boolean, file-type, size and date filters,
regex:,fuzzy:,similar:,content:,tag:, duplicate finding, empty folders, Quick Look, saved searches, sorting, live updates, and the index cache. - A free license unlocks: the command-line tools (
--search,--duplicates,--du,--http,--mcp) and the in-app Fast Regex & Similarity accelerator.
Get & activate a key
- On the download page, enter your name and email — we'll email you a free key.
- In Linen, choose Enter License… from the menu bar and paste the key. (From the command line:
linen --license "<your-key>".)
9 · Command-line tools free license
The same engine is scriptable, like Everything's es.exe. It prints matching full paths, one per line, so you can pipe it anywhere.
The command lives inside the app bundle. For convenience, link it to a short linen command:
# one-time: make a short `linen` command
sudo ln -s /Applications/Linen.app/Contents/MacOS/Linen /usr/local/bin/linen
Search
# largest Swift files under a folder linen --search "*.swift" --in ~/code --sort size --desc --limit 20 # images modified this week, anywhere under home linen --search "image: dm:thisweek" --in ~
Options: --in <path> (root, default /), --limit <n> (0 = unlimited), --sort name|path|size|date, --desc / --asc. There's no resident service, so each call builds a fresh index — scope it with --in for speed.
Duplicates & disk usage
# duplicate sets under a folder + how much space they waste linen --duplicates --in ~/Pictures linen --duplicates "ext:mov" --in ~/Movies --limit 20 # the largest directories — "what's eating my disk" linen --du ~ --limit 20
Saved searches
linen --saved --add "Big media" "ext:mp4 size:>100mb" linen --saved # list all linen --search "$(linen --saved 'Big media')" --in ~
10 · Web UI & JSON API free license
Run a built-in web server to search from a browser — on this Mac or another device on your network.
linen --http 8080 --in ~ # search UI at http://localhost:8080 linen --http 8080 --allow-download # also allow downloading matched files
The URL query string is Everything-compatible, so the same endpoint returns JSON for scripting:
# 20 largest Swift files as JSON
curl 'http://localhost:8080/?search=*.swift&json=1&sort=size&ascending=0&count=20'
Parameters include search (s/q), json, count, offset, case, wholeword, path, regex, sort, and ascending. There's also a disk-usage page at /du. The server binds to 127.0.0.1 by default (pass --host 0.0.0.0 to expose it on your LAN), and downloads are off unless you pass --allow-download — and even then are restricted to files actually in the index, so a client can't request an arbitrary path.
11 · AI agents (MCP) free license
Linen speaks the Model Context Protocol, so an AI agent — GitHub Copilot, Claude, VS Code — can use it as a fast, local, read-only "find files on this Mac" tool.
It runs over stdio (JSON-RPC 2.0): no network socket is opened, and only names, paths, sizes and dates are returned — never file contents.
linen --mcp # index the whole startup volume (loads the cache, starts fast) linen --mcp --in ~/Projects # scope an agent to one folder
Register it with a client — e.g. VS Code's mcp.json or Claude Desktop's claude_desktop_config.json:
{
"servers": {
"linen": {
"command": "/Applications/Linen.app/Contents/MacOS/Linen",
"args": ["--mcp"]
}
}
}
Then an agent can ask things like "find the largest videos under ~/Movies", "are there duplicate PDFs in my Downloads?", or "which Swift files mention QLPreviewPanelDelegate?" and Linen answers in milliseconds, entirely on-device.
| Tool | What it does |
|---|---|
search_files | Name/path search with the full query language, plus sort / order / limit / within |
search_content | Grep inside files — returns matching files with line numbers and lines (scope with ext and/or within) |
find_duplicate_files | Files with identical content, and the reclaimable space |
disk_usage | The largest directories by recursive size |
index_stats | Indexed item count, root, and readiness |
12 · Private by design
Linen does its work entirely on your Mac.
The index lives on your device and never leaves it. There's no telemetry, no analytics, and no account. Linen reads file metadata locally to build the index; content: reads a file only when you ask it to, and nothing read from disk is ever transmitted. The only personal data we ever receive is the email address you choose to give us to get a free license. See the full Privacy Policy for details.
Ready to find anything?
Download Linen, grant Full Disk Access, and press ⌥Space.