# Query: search, ask, context, symbol, why, status

Search the docs, ask cited questions, read triage cards and symbols, trace why code exists, and check sync state from the terminal with repowise search.

## `repowise search`

Search the documentation by keyword, meaning, or symbol name. The terminal
side of the [`search_codebase`](https://docs.repowise.dev/mcp/search-codebase) MCP tool.

```bash
repowise search QUERY [PATH] [OPTIONS]
```

| Name | Type | Default | Description |
|---|---|---|---|
| `--mode` | string | `fulltext` | Search mode: fulltext, semantic, symbol, auto, concept, path, hybrid |
| `--limit` | number | `10` | Max results |
| `--repo` | string |  | Scope to a specific workspace repo by alias |
| `--all` | boolean | `false` | Fan out across every workspace repo and merge results |
| `--workspace / --no-workspace` | boolean |  | Force workspace / single-repo mode |
| `--format` | string | `table` | Output: table or json |
| `--full` | boolean | `false` | Emit the complete tool payload as JSON (implies --format json) |

```bash
repowise search "auth token validation"
repowise search "auth token validation" --mode semantic --limit 20
repowise search "GraphBuilder" --mode symbol
repowise search "cli/output.py" --mode path
repowise search "where is resolve_console_width called" --mode auto
repowise search "rate limit" --repo backend     # workspace, one repo
repowise search "rate limit" --all              # workspace, fan-out
```

Modes:

- **fulltext** / **semantic**: both route to the tool's fused `concept`
  mode, which combines full-text and vector search through RRF rather than
  choosing one. `semantic` falls back to full-text alone on a keyless index.
- **symbol**: symbol name match.
- **auto**, **concept**, **path**, **hybrid**: the underlying
  `search_codebase` tool's own mode spellings, accepted directly.

`--format json` emits a trimmed projection (`score`, `title`, `page_type`,
`path`, `snippet` per hit, plus `candidates`). `--full` returns the tool's
raw dict.

There is no `repowise query` command. For a synthesized answer rather than a
keyword lookup, use `repowise ask` below, the MCP
[`get_answer`](https://docs.repowise.dev/mcp/get-answer) tool from your editor, or the
**Chat** tab in the web UI (`repowise serve`).

---

## `repowise ask QUESTION`

Answer a question about the codebase, with citations. The same synthesis the
[`get_answer`](https://docs.repowise.dev/mcp/get-answer) MCP tool performs: hybrid retrieval followed by an LLM answer
over what it found, so this is the one command in this cluster that costs an
LLM call.

```bash
repowise ask QUESTION [OPTIONS]
```

| Name | Type | Default | Description |
|---|---|---|---|
| `--scope` | string |  | Restrict retrieval to a path prefix (e.g. packages/cli/) |

```bash
repowise ask "how does the retry backoff work?"
repowise ask "where is the session cookie set?" --format json
repowise ask "how is width resolved?" --scope packages/cli/
repowise ask "why is auth split across two modules?" --full
```

`confidence: high` is content-grounded, so it can be cited directly. A
low-confidence answer returns `best_guesses` (a file plus why it's in the
running) instead of an empty one.

---

## `repowise context TARGETS...`

Triage card for files, modules, or symbols, from
[`get_context`](https://docs.repowise.dev/mcp/get-context): title, summary, architectural
layer, hotspot and bug-fix history, doc freshness, and the shape of the
verified skeleton. Relationships and risk signals, not source bytes. Batch
targets in one call.

```bash
repowise context TARGETS... [OPTIONS]
```

| Name | Type | Default | Description |
|---|---|---|---|
| `--include` | string |  | Opt-in block, repeatable: full_doc, ownership, last_change, callers, callees, references, metrics, community, decisions, health, skeleton, skeleton+, doc_drift, symbols, changes, provenance, suspects |
| `--no-compact` | boolean | `false` | Add structure, imports, and docstrings to each card |
| `--symptom` | string |  | Issue text, an error or a stack trace for --include suspects to rank against |

```bash
repowise context src/api/routes.py src/api/auth.py
repowise context src/api/routes.py::login --include callers --include metrics
repowise context src/api/routes.py --include skeleton   # + the file's source
repowise context src/billing/invoice.py --include suspects --symptom "TypeError: total is undefined"
```

No source bytes by default. Pass `--include skeleton` for the whole file,
body-elided and line-verified, in one call, or just read the file.

---

## `repowise symbol SYMBOL_ID`

Read one function, class, or constant with live-verified line bounds, as
[`get_symbol`](https://docs.repowise.dev/mcp/get-symbol) does.
`source` arrives in the same line-numbered format a file read produces;
`verified: true` means the bounds were checked against the live file.

```bash
repowise symbol SYMBOL_ID [OPTIONS]
```

| Name | Type | Default | Description |
|---|---|---|---|
| `--context-lines` | number |  | Extra lines before and after the body (0-50) |
| `--query` | string |  | Omission refs only: regex or substring filter on the restored lines |

```bash
repowise symbol "src/api/routes.py::login"
repowise symbol "src/api/routes.py:140-180"     # live range read
repowise symbol "repowise#a1b2c3d4e5f6"          # a distill omission ref
```

An ambiguous id (overloads, re-exports) returns every matching body rather
than silently picking one. A truncated body carries a `continuation` you can
pass straight back to `repowise symbol`.

---

## `repowise why [QUERY]`

Why the code is shaped this way: [decision records](https://docs.repowise.dev/intelligence/decisions),
rationale, and git archaeology, through [`get_why`](https://docs.repowise.dev/mcp/get-why). Worth running before a refactor or a deliberate divergence
from a pattern.

```bash
repowise why [QUERY] [OPTIONS]
```

| Name | Type | Default | Description |
|---|---|---|---|
| `--target` | string |  | File path to anchor the search to. Repeatable |

```bash
repowise why "why is auth using JWT?"           # question
repowise why src/api/auth.py                     # governing decisions + origin story
repowise why "why the retry cap?" --target src/api/client.py
repowise why                                     # decision health dashboard
```

Falls back to git archaeology when a path has no decisions, so it's never
empty.

### Shared options: `ask`, `context`, `symbol`, `why`

These four are thin adapters over the MCP tools of the same name, so they
share one option block:

| Name | Type | Default | Description |
|---|---|---|---|
| `--path` | string |  | Repo (or workspace) root. Defaults to the current directory |
| `--repo` | string |  | Workspace repo alias to query |
| `--no-workspace` | boolean | `false` | Force single-repo mode even inside a workspace |
| `--format` | string | `table` | table or json |
| `--full` | boolean | `false` | Emit the complete tool payload as JSON (implies --format json) |

The repo is `--path` here rather than a trailing positional: `context`
accepts a variadic list of targets, which would swallow a trailing path.

`--format json` emits a trimmed CLI projection, not the tool's whole
response. `--full` returns the raw dict, the same one an editor's MCP
client receives. Nothing that changes the answer is ever trimmed: an error,
a not-found, a did-you-mean list, a truncation marker, a continuation
token, and ambiguity signals all survive at every format.

---

## `repowise status`

Show the index's [mode](https://docs.repowise.dev/cli/indexing#modes) and the command that
upgrades it, the sync state and page statistics: last sync commit, total
pages, provider/model, token usage, and a per-type page breakdown. A
Decisions row appears while decisions a keyless index skipped are still
pending.

```bash
repowise status [PATH] [OPTIONS]
```

| Name | Type | Default | Description |
|---|---|---|---|
| `--workspace / -w` | boolean | `false` | Show status for every repo in the workspace |
| `--no-workspace` | boolean | `false` | Force single-repo status even when invoked from a workspace root |
| `--format` | string | `table` | table or json |

```bash
repowise status
repowise status --workspace
repowise status --no-workspace
repowise status --format json   # mode, counts and the next command
```

After an upgrade that changed the health analyzer or the security scanner,
`status` prints one line naming what the next `repowise update` redoes:
re-scoring health, rescanning security, or both. `--format json` reports it
as `rescore_pending` (`health`, `security`).

In workspace mode, the table includes a **Docs** column with each repo's page
count and a per-repo docs-status block listing skip reasons and the exact
remediation command.