> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiroleague.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Full-text search over tasks with `hirotm query search` (FTS5).

**`hirotm query search`** runs **FTS5** full-text search across indexed task fields: **title**, **body**, **list** name, **group** label, and **status** label. Output uses the same [global **`--format`**](/task-manager/cli/cli-commands#response-format) as other commands (this subcommand does not add its own format or view flags).

The server must be running—see [Server Operations](/task-manager/cli/server). For shared flags (**`--profile`**, **`--client-name`**), see [hirotm CLI](/task-manager/cli/cli-commands).

**Access policy**

* **No `--board`:** hits only include tasks on boards the CLI is allowed to **read** (server-side filter for the CLI principal).
* **With `--board`:** that board must exist, and the CLI needs **`readBoard`** for it—otherwise you get **404** (unknown board) or **403** (no access). See [CLI access policy](/task-manager/cli/cli-access-policy).

Malformed FTS syntax (for example unmatched quotes) returns **400** with **`Invalid search query`**.

**Sort:** hits are ordered by **BM25 relevance score** ascending (**lower** = **better** match). Paging uses that order. See [Default sort order](/task-manager/cli/cli-commands#default-sort-order).

***

## `query search`

The query is all arguments after **`search`**, joined with spaces—use **quotes** for phrases.

| Option                 | Type                                            | Required                                      | Description                                                                                                                                                                                                           |
| ---------------------- | ----------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<query...>`           | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="check" color="green" size={14} /> | Search text (non-empty).                                                                                                                                                                                              |
| `--board <id-or-slug>` | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Limit hits to one board.                                                                                                                                                                                              |
| `--limit <n>`          | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Page size (**default 20** when omitted on the CLI, **max 500** per request).                                                                                                                                          |
| `--offset <n>`         | <Badge size="sm" color="purple">integer</Badge> | <Icon icon="minus" size={14} />               | Skip this many hits (default **0**).                                                                                                                                                                                  |
| `--page-all`           | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Fetch every page at the current **`--limit`** and merge hits.                                                                                                                                                         |
| `--count-only`         | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Total hits only ([Paging](/task-manager/cli/cli-commands#paging-list-results)); not with **`--limit`**, **`--offset`**, **`--page-all`**, or **`--fields`**.                                                          |
| `--no-prefix`          | <Badge size="sm" color="orange">flag</Badge>    | <Icon icon="minus" size={14} />               | Do not treat the **last token** as a prefix match (no implicit **`*`**).                                                                                                                                              |
| `--fields <keys>`      | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Comma-separated API keys per hit. Allowed: `taskId`, `boardId`, `boardSlug`, `boardName`, `listId`, `listName`, `title`, `snippet`, `score`. See [Field projection](/task-manager/cli/cli-commands#field-projection). |
| `--client-name <name>` | <Badge size="sm" color="blue">string</Badge>    | <Icon icon="minus" size={14} />               | Optional label on the request (read-only here).                                                                                                                                                                       |

Accepts global **`-q` / `--quiet`** (with **`--format ndjson`**); default field **`taskId`**. See [Pipe-friendly quiet](/task-manager/cli/cli-commands#pipe-friendly-quiet).

**Prefix matching (default)**

Unless you pass **`--no-prefix`**, the CLI asks the server to **prefix-match the last token** (for example **`drag`** can match **`dragging`**). If the query looks like an advanced FTS expression—**quotes**, **parentheses**, or **column-style** syntax—the server uses your string **as-is** (no automatic **`*`** on the last word).

**CLI Examples**

```bash theme={null}
hirotm query search "login bug"
hirotm query search "login bug" --count-only
hirotm query search drag
hirotm query search password --board sprint --limit 10
hirotm query search "exact term" --no-prefix
hirotm query search docs --limit 100 --offset 100
hirotm query search refactor --page-all --limit 200
hirotm query search docs --fields taskId,boardSlug,title
hirotm query search backlog --format human                  # table
```

**AI Agent Examples**

<Prompt description="Search tasks for &#x22;release notes&#x22; on board sprint, JSON, limit 15." actions={["copy", "cursor"]}>
  Search tasks for "release notes" on board sprint, JSON, limit 15.
</Prompt>

<Expandable title="Example responses" defaultOpen={false}>
  <CodeGroup>
    ```json json theme={null}
    {"taskId":88,"boardId":1,"boardSlug":"sprint","boardName":"Sprint","listId":2,"listName":"Doing","title":"Fix login bug","snippet":"…password reset flow…","score":1.25}
    ```

    ```json error theme={null}
    {
      "error": "Board not found",
      "status": 404,
      "url": "http://127.0.0.1:3002/api/search?..."
    }
    ```

    ```json invalid query theme={null}
    {
      "error": "Invalid search query"
    }
    ```

    ```text human theme={null}
    Board            Id  Title                         Snippet
    -------------- --- --------------------------- --------------------------------
    sprint           88 Fix login bug               …password reset…
    total 1 · showing 1 · limit 20 · offset 0
    ```
  </CodeGroup>
</Expandable>

| Field                            | Meaning                                                                           |
| -------------------------------- | --------------------------------------------------------------------------------- |
| **`taskId`**                     | Global task id (use with **`hirotm tasks`**).                                     |
| **`boardSlug`**, **`boardName`** | Where the task lives.                                                             |
| **`listName`**                   | Column name for the task.                                                         |
| **`snippet`**                    | Short excerpt with match context.                                                 |
| **`score`**                      | BM25-style score (**lower** is a **better** match in the current implementation). |

***

## Learn more

Run **`hirotm help query search`** for the full help text. Command summaries also appear in [hirotm CLI](/task-manager/cli/cli-commands).