Search

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 as other commands (this subcommand does not add its own format or view flags). The server must be running—see Server Operations. For shared flags (--profile, --client-name), see hirotm CLI. 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.

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.

`query search`

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

Option	Type	Description
`<query...>`	string	Search text (non-empty).
`--board <id-or-slug>`	string	Limit hits to one board.
`--limit <n>`	integer	Page size (default 20 when omitted on the CLI, max 500 per request).
`--offset <n>`	integer	Skip this many hits (default 0).
`--page-all`	flag	Fetch every page at the current `--limit` and merge hits.
`--count-only`	flag	Total hits only (Paging); not with `--limit`, `--offset`, `--page-all`, or `--fields`.
`--no-prefix`	flag	Do not treat the last token as a prefix match (no implicit *``**).
`--fields <keys>`	string	Comma-separated API keys per hit. Allowed: `taskId`, `boardId`, `boardSlug`, `boardName`, `listId`, `listName`, `title`, `snippet`, `score`. See Field projection.
`--client-name <name>`	string	Optional label on the request (read-only here).

Accepts global -q / --quiet (with --format ndjson); default field taskId. See 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

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

Search tasks for "release notes" on board sprint, JSON, limit 15.

Open in Cursor

Show Example responses

{"taskId":88,"boardId":1,"boardSlug":"sprint","boardName":"Sprint","listId":2,"listName":"Doing","title":"Fix login bug","snippet":"…password reset flow…","score":1.25}

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

{
  "error": "Invalid search query"
}

Board            Id  Title                         Snippet
-------------- --- --------------------------- --------------------------------
sprint           88 Fix login bug               …password reset…
total 1 · showing 1 · limit 20 · offset 0

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.

Get Started

CLI

Hiro Developers

`query search`

Learn more

​query search

​Learn more

`query search`

Learn more