Command Line Interface (CLI) guide

How to search files from Terminal with quick-search

The Quick Search Command Line Interface (CLI) reuses the shared Mac index from Terminal, shell scripts, pipelines, Shortcuts, automation tools, and AI-assisted workflows after CLI support is enabled in the macOS app.

1. Set up folders in the Mac app first

Add folders and build the initial index in the Quick Search Mac app. This keeps folder authorization aligned with macOS security-scoped permissions. The CLI then uses that same shared local index for update, search, and status commands.

quick-search updatequick-search status

2. Search with default AND matching

By default, multiple terms narrow results with AND matching. Add an extension filter when you know the file type.

quick-search search report 2026 --ext pdf

3. Choose the output format

Use paths-only output for shell pipelines and JSON output when an AI tool, script, or automation needs structured metadata it can read reliably.

quick-search search report --ext pdf --paths-onlyquick-search search report --ext pdf --json --limit 10

4. Pipeline examples

--paths-only prints one file path per line, which works well with standard shell tools.

quick-search search report --ext pdf --paths-only | headquick-search search report --ext pdf --paths-only | pbcopyquick-search search report --ext pdf --paths-only | xargs -I {} open "{}"

5. Use JSON for AI and automation

--json returns structured fields such as name, path, relative path, extension, root folder, and file size. Use --limit to keep AI context small and predictable.

quick-search search contract --json --limit 10

FAQ

Can the CLI add folders or build the first index?

No. Add folders and build the initial index in the Mac app. The CLI is designed for update, search, and status against the app-authorized shared index.

Can I search by extension only?

Yes. Use an extension filter when the filename terms are unknown or unnecessary.

Does the Command Line Interface (CLI) use a different index?

No. The CLI and macOS app use the same shared local index after CLI support is enabled.