Docs Search

Reference for breyta docs find, supported query syntax, and result-shaping
flags.

Quick Answer

Use breyta docs find "<query>" to search the public docs corpus. Default
results are rg-like: each hit carries ref, source, matchedFields, a
bounded snippet, and nextCommand for focused docs show inspection.

Query behavior:

• plain terms are supported
• multiple plain terms default to AND
• quoted phrases are supported
• Lucene-style boolean and fielded queries are supported by the indexed search
  path
• malformed Lucene syntax is escaped and retried as a literal query instead of
  failing immediately

Command Surface

breyta docs find "flows push"
breyta docs find --q "source:cli release"
breyta docs find "files materialize" --limit 5 --format json
breyta docs show reference-cli-commands
breyta docs fields http response-as persist
breyta docs sync --out ./.breyta-docs --clean

Query can be provided either:

• as the positional [query]
• or with --q

Do not provide both in the same invocation.

Field-Level Step Config Lookup

Use breyta docs fields <step-type-or-doc-slug> [field ...] when you need step
configuration details without opening a full reference page.

Examples:

breyta docs fields http
breyta docs fields http response-as persist retry --format json
breyta docs fields files source paths --section read
breyta docs fields :llm model output tools
breyta docs fields reference-step-files op source paths --format markdown

Omit field names for a compact config-object overview. Pass multiple fields when
only selected config keys matter. Add --section <heading> when a reference
page has operation-specific tables, such as files read or table query. Use
docs show <slug> --section "Canonical Shape" only when field rows are not
enough.

Plain-Term Queries

Plain terms search across the indexed docs fields. Multi-term queries default to
AND, so all terms must match somewhere in the indexed page content or metadata.

Examples:

breyta docs find "flows push"
breyta docs find "jobs worker"
breyta docs find "install discover"

Current indexed text fields include:

• title
• slug_text
• tags
• category
• source
• tag
• markdown

title and slug_text are weighted above body markdown, so pages with the term
in the title or slug usually rank higher.

Phrase Queries

Use double quotes when the words should stay adjacent and in order:

breyta docs find "\"flow release\""
breyta docs find "\"jobs worker run\""

Boolean Queries

The indexed search path supports Lucene-style boolean expressions.

Common operators:

• AND
• OR
• NOT
• leading - for exclusion
• parentheses for grouping

Examples:

breyta docs find "\"live\" AND source:flows-api"
breyta docs find "install OR discover"
breyta docs find "bindings -oauth"
breyta docs find "(jobs OR worker) AND source:cli"

Because the parser defaults to AND, these are equivalent:

breyta docs find "flows push"
breyta docs find "flows AND push"

Fielded Queries

Use field:value to target one indexed field explicitly.

Recommended field filters:

• source:cli
• source:flows-api
• category:reference
• category:operate
• tag:end-user

Examples:

breyta docs find "source:cli release"
breyta docs find "category:reference jobs"
breyta docs find "tag:end-user discover"

Advanced indexed fields also accept explicit targeting:

• title:
• slug_text:
• tags:
• tag:
• markdown:

Examples:

breyta docs find "title:install"
breyta docs find "slug_text:reference"
breyta docs find "markdown:\"jobs worker\""

Prefer source, category, and tag when you want predictable metadata
filtering. The other fields are useful for advanced debugging and ranking
inspection.

Source Flag Vs Query Filter

There are two ways to constrain docs by source:

breyta docs find "release" --source cli
breyta docs find "source:cli release"

Use --source when the source filter is a simple top-level constraint.
Use source: inside the query when you want it to live inside a larger boolean
expression.

--source supports:

• cli
• flows-api
• all

Pagination And Output Controls

Result shaping flags:

• --limit <n>
• --offset <n>
• --format tsv|json
• --no-header
• --with-summary
• --with-snippets
• --explain
• --timeout-seconds <n>

Examples:

breyta docs find "install" --limit 20 --offset 20
breyta docs find "release" --with-snippets --format json
breyta docs find "source:cli release" --explain --format json

Behavior:

• --with-summary fetches each matched page and includes the first useful
  summary line in CLI output
• --with-snippets asks the API to include a short matched text snippet
• --explain asks the API to include per-result query explanation data
• --format json exposes richer fields than the default TSV view

JSON Result Fields

When --format json is used, each result page can include:

• slug
• title
• source
• category
• order
• tags
• score
• matchedFields
• snippet
• explain
• description

The top-level JSON meta block can include:

• total
• query
• limit
• offset
• withSnippets
• explain
• degraded

Degraded Search Behavior

The search path has two important fallback behaviors:

1. If Lucene parsing fails, the raw query is escaped and retried as a literal
   text query.
2. If indexed search fails more broadly, the API degrades to simpler catalog
   search and marks the JSON response with meta.degraded=true.

That means advanced boolean or fielded semantics are best-effort in degraded
mode. If you are debugging exact query behavior, use:

breyta docs find "<query>" --format json --explain

and inspect the returned meta.degraded and per-result explain fields.

Example Patterns

Related

• CLI Commands
• Reference Index
• Start Here