Olares Search
Apps & Automationolares-searchOlares Search is an Agent Skill for apps & automation published in the beclab/Olares repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/beclab/Olares/blob/HEAD/cli/skills/olares-search/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/olares-search, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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--helpcannot give: what the index covers, howsearchdiffers fromfiles, 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 syncanswers "which file CONTAINS this text" by querying the pre-built per-user index.search appanswers "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, useolares-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/syncresults show a title, a location (resource URI / path / repo), and a content snippet with the match.--output jsonemits the raw upstream rows verbatim.appresults show title, app id, entrance name, state, and URL.--output jsonemits structured app rows.
Search model
drive
- Session-based: bootstraps
/api/search/init, pages deeper with/api/search/more(samereqid), best-effort cleanup via/api/search/cancel. --type aggregate(default) is full-content search;--type file_namematches on filename only.--limit(default 20) caps results;--offsetpages./initalways 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--limitis effectively capped around 50, and an--offsetpast the end prints "no results" rather than erroring.
sync
- Single endpoint:
POST /api/search/sync {query}(the proxy ignores any paging fields). - No
--typeflag (sync does not support search mode selection).--limit/--offsetare 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
runningapp 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_namehits 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 aggregatequery 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 witholares-cli settings search dirs list). This lives in theolares-settingsskill (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 excludessubcommand 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 statussurfaces aFailurescount (use-o jsonfor the per-file detail) — check it first when content search misses a file you expect.
Examples
# Full-content search of Drive.
olares-cli search drive report
# Multi-word phrase, filename-only match.
olares-cli search drive "design doc" --type file_name --limit 50
# Search Sync (Seafile) libraries, paged, JSON for scripting.
olares-cli search sync notes --offset 20 -o json
# Search installed applications.
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 |