# swarmfile-search

`swarmfile-search` runs full-text search across the local Swarmfile metadata cache, with fallback to the hub. It's a standalone binary for searching from a terminal or a script, rather than the dashboard omnibox. Every desktop installer carries it, and the Linux `.deb`, macOS `.pkg` and Windows installers put it on `PATH` (`/usr/bin` on Linux, `/usr/local/bin` on macOS, or the Windows install folder); a macOS `.dmg`-only install needs one `.pkg` (or **Diagnostics → Reinstall**) run for that entry.

The local cache is entries-only: it indexes file and folder names in a local full-text index, and it's what a plain query checks first. Project and people (principal) name matches only come from the hub fallback - the local cache doesn't mirror those, so a query for a project or person name needs a hub round-trip (or `--remote`) to find anything. On the hub the two halves also live in different places: entries are indexed per project, while project and people names are org-wide. A query scoped with `--project` (or `$SWARMFILE_PROJECT_ID`) therefore asks both routes and merges them, so you still get project/people matches alongside the file hits; an unscoped hub query searches project and people names only - **file hits from the hub need `--project`**, or a warm local cache. Either way, it's a metadata search - it finds things by name, not by file contents.

For the conceptual overview of how search resolves results and where else you can search from, see [Search](https://swarmfile.com/docs/guides/search).

## Usage

```bash
swarmfile-search <query>
```

## Flags

| Flag | Description |
|---|---|
| `--project` | Scope the search to a single project by ID. Defaults to `$SWARMFILE_PROJECT_ID` when set |
| `--limit` | Maximum results. Default `20` |
| `--remote` | Force the search against the hub. Conflicts with `--local-only` |
| `--local-only` | Force the search against the local cache only. Conflicts with `--remote` |
| `--json` | Print raw JSON instead of a human-readable list. Emits the hub's `{files, folders, projects, principals}` shape plus a top-level `source` field |

## Examples

Plain query across the local cache, falling back to the hub if needed:

```bash
swarmfile-search "concept_v3"
```

Scoped to a project, capped at 5 results, local cache only:

```bash
swarmfile-search "elevation" --project proj_xyz789 --local-only --limit 5
```

JSON output for scripting:

```bash
swarmfile-search "plan.dwg" --json
```

Alongside the hub-shaped `{files, folders, projects, principals}` object, `--json` adds a top-level `source` field so a script can tell where the results came from without changing the other keys - `local`, `local (no fallback)`, `remote`, or `remote (local fallback)`.