search
poly search runs the same semantic and full-text search engine behind the Poly app, from the terminal. It can search by meaning, exact text, metadata, or similarity to another file.
Usage
poly search [QUERY]
Running poly search with no arguments prints help. By default a query runs in dual mode — both smart (semantic) and full-text search together. Use --smart <QUERY> for semantic-only, or --text <PHRASE> for full-text-only. If you pass filters without a query, poly search runs a metadata-only search. See Searching for how these modes work in the app.
Filters
poly search --help has the full list; these are grouped highlights:
| Group | Representative flags |
|---|---|
| Name | --name <GLOB>, --name-exact, --name-starts, --name-contains |
| Type / mime | --include-type / --exclude-type, --include-mime / --exclude-mime |
| Location | --in <FOLDER-REF>, --under <FOLDER-REF>, --search-location <FOLDER-REF> |
| Dates | --created-after / --created-before, --modified-after / --modified-before (also accessed, edited, added) |
| Size | --size-gt, --size-lt (and -gte/-lte; accept KB/MB/GB suffixes) |
| Tags / rating | --tag <TAG>, --rating-gte, --rating-lte |
| Similarity | --near-file <FILE-REF>, --near-color <COLOR> |
| Sort | --sort <FIELD> (repeatable; prefix - to reverse) |
Dates accept fuzzy values like "7 days ago". Size filters take KB/MB/GB suffixes. --search-location is repeatable but conflicts with --in/--under.
Similarity search
--near-file <FILE-REF> finds files visually or semantically similar to a given file, and --near-color <COLOR> (up to 8 colors) finds files by dominant color — see Searching by File and Searching by Color. Snippet modifiers like --near-file-start-time/--near-file-end-time, --near-file-pages, and --near-file-start-line/--near-file-end-line narrow the similarity match to part of the reference file.
Other flags
| Flag | Description |
|---|---|
--offset <N> | Pagination offset (default 0). |
--limit <N> | Result count (default 10 in dual mode, 20 in single-mode). |
-l, --long / --columns | Detailed columns, or a custom column list. |
--show-all | Include smart matches below the relevance cutoff. |
--ignore-files-in-query <bool> | Whether to strip file-like tokens from the query text (default true). |
Examples
# Dual smart + text search
poly search "Q3 budget projections"
# Semantic-only search scoped to a folder
poly search --smart "vacation photos from Italy" --under //Home/photos
# Full-text search for an exact phrase
poly search --text "invoice #4471"
# Metadata-only: large PDFs modified in the last week
poly search --include-type pdf --size-gt 5MB --modified-after "7 days ago"
# Find files visually similar to a reference image
poly search --near-file //Home/photos/sunset.jpg
# Find files by dominant color
poly search --near-color teal --near-color orange
Related
find— name/path/type lookups from the local cache, no server round-trip.mksearch— save a search as a smart folder.- Searching — search modes and filters in the Poly app.