| name | olares-search |
| version | 1.2.0 |
| description | Olares search via olares-cli search — the Desktop global search over Drive files, Sync (Seafile) libraries, and installed applications, with paging and JSON output. Use for Olares search, full-text search, find a file by content, Text Search, global search, search apps. |
| compatibility | Requires olares-cli on PATH and active Olares profile |
| metadata | {"openclaw":{"requires":{"bins":["olares-cli"]}}} |
search (Desktop global search)
CRITICAL — before doing anything, load the olares-shared skill first (profile selection, login, token refresh, auth-error recovery). Flag reference: olares-cli search <subcommand> --help.
Source of truth for flags is always olares-cli search <subcommand> --help. This file only carries what --help cannot give: what the index covers, how search differs from files, the session model, and the error → fix matrix.
When to use
- Find content by keyword across the user's data: "where is the file that mentions X", "search my drive for invoice", full-text / Text Search, Desktop global search.
- Find installed applications by title: "open wise", "search for firefox app".
- Subcommands:
drive (user Drive files), sync (Seafile / Sync libraries), app (installed applications).
- Keywords: Olares search, full-text search, find by content, Text Search, global search, search drive, search sync, search app.
Anything outside this scope -> see the Skill suite map in ../olares-shared/SKILL.md (already loaded as the suite prerequisite).
Mental model: search drive / search sync answers "which file CONTAINS this text" by querying the pre-built per-user index. search app answers "which installed app matches this name". It is not lifecycle inventory (market list --mine / market status) or resource ranking (dashboard applications). To LIST or READ a known path, use olares-files (files ls / files cat / files download).
What it is
olares-cli search is the CLI mirror of the Olares Desktop global search dialog (reached via the Dock search icon / Shift+Space). It is a command group with three subcommands:
| Subcommand | Backend | Purpose |
|---|
search drive <keyword> | search3 index (/api/search/init + /more) | Full-content / filename search of Drive files |
search sync <keyword> | /api/search/sync | Search Seafile/Sync libraries |
search app <keyword> | /server/myApps (local filter) | Search installed applications by entrance title |
Multiple words are joined into one keyword (quote multi-word phrases to be explicit).
drive / sync results show a title, a location (resource URI / path / repo), and a content snippet with the match. --output json emits the raw upstream rows verbatim.app results show title, app id, entrance name, state, and URL. --output json emits structured app rows.
Search model
drive
- Session-based: bootstraps
/api/search/init, pages deeper with /api/search/more (same reqid), best-effort cleanup via /api/search/cancel.
--type aggregate (default) is full-content search; --type file_name matches on filename only.--limit (default 20) caps results; --offset pages. /init always returns the first 20 hits and ignores offset/limit, so the CLI honors them itself: when the requested window fits inside those 20 hits (or the search returned fewer), it is sliced client-side with no extra call; only a window past the first 20 triggers /more (limit clamped to the backend's 1-100). A single search resolves at most ~50 hits server-side, so --limit is effectively capped around 50, and an --offset past the end prints "no results" rather than erroring.
sync
- Single endpoint:
POST /api/search/sync {query} (the proxy ignores any paging fields).
- No
--type flag (sync does not support search mode selection). --limit / --offset are applied client-side by the CLI (the backend returns the full result set and does not paginate), so they still work but every call fetches everything first.
app
- Fetches installed apps from
/server/myApps, expands visible entrances, filters by case-insensitive substring match on the entrance title (falling back to the app title when an entrance declares none).
- Returns all matches in one response (no
--limit / --offset).
- Skips uninstalled/failed apps and invisible entrances (same rules as the Desktop SPA). For a
running app the row shows the per-entrance state.
Indexing (drive / sync only)
Indexing is asynchronous on the server: a just-created/just-uploaded file may not be searchable until the index catches up. A miss is "not indexed yet", not necessarily "absent" — confirm a known path with files ls, check progress with olares-cli settings search status, and force a full reindex with olares-cli settings search rebuild (both in the olares-settings skill).
Index coverage (drive only)
Two distinct indexes back Drive search — knowing which one a query hits explains most "why didn't it find X" cases.
- Filenames — indexed broadly by default. Effectively every Drive file's name is indexed, so
--type file_name hits almost anywhere. The only opt-outs are paths matching an exclude pattern (a per-user regex list: built-in non-removable entries plus user-added ones).
- Full-text (content) — only
/Documents/ by default. A --type aggregate query matches file contents only where content indexing is enabled, which by default is just the Drive /Documents/ directory. Everywhere else you get filename matches but no in-content hits. Supported full-text formats: pdf, Word (doc/docx), Excel (xls/xlsx), csv, rtf, plus a wide range of plain-text and source-code extensions (txt/md/json/xml/yaml and many more).
- To make another directory full-text searchable, add it to the full-content index:
olares-cli settings search dirs add <path> (inspect the current set with olares-cli settings search dirs list). This lives in the olares-settings skill (settings search).
- To see what is being blocked, the exclude patterns are viewable/editable only in the Olares Settings SPA → Search → File search (the CLI's
settings search excludes subcommand is not wired up); built-in patterns cannot be removed.
- Full-text extraction can fail per file (encrypted / corrupt / oversized), so a supported-format file in an indexed directory may still have no in-content hits.
olares-cli settings search status surfaces a Failures count (use -o json for the per-file detail) — check it first when content search misses a file you expect.
Examples
olares-cli search drive report
olares-cli search drive "design doc" --type file_name --limit 50
olares-cli search sync notes --offset 20 -o json
olares-cli search app wise
olares-cli search app firefox -o json
Common errors
| Symptom | Cause | Fix |
|---|
a non-empty search keyword is required | No keyword given | Pass <keyword> (quote phrases) |
unsupported --type "<x>" (allowed: aggregate, file_name) | Unknown search mode on drive | Use aggregate or file_name (drive only) |
--limit must be a positive integer / --offset must not be negative | Bad paging values | Use --limit > 0, --offset >= 0 |
no results but the file exists | Index hasn't caught up, or content not indexed | Check settings search status for progress/failures; verify the path with files ls. If it's a content miss, confirm the dir is in settings search dirs, then settings search rebuild |
no results for app search | No installed app matches the keyword | Try a shorter keyword; confirm the app is installed and visible |
server rejected the access token / token invalidated | Auth | See ../olares-shared/SKILL.md recovery table |
