Find a definition or every reference

tovio semantic find-def <moniker>tovio semantic find-refs <moniker>

Symbols are addressed by SCIP-style descriptor moniker — a stable, language-agnostic name rather than a text pattern.

Why not grep

Grep finds the string. This finds the symbol: it distinguishes a method from an unrelated function with the same name, and it does not match comments or strings.

For "what breaks if I change this", find-refs gives an answer you can act on where a text search gives you a pile to sift.

Getting a moniker

The reliable route is to search for one, because search is the query that does not require you to already know the answer:

tovio semantic search greet

It ranks indexed definitions against what you actually typed and prints each hit's moniker, its file and line, and how many references it has. The default is a screenful; raise it with --limit.

In VS Code, the Semantic view has a Copy Symbol Moniker action on its right-click menu — but only for a symbol that view is already showing, which means one that turned up in an interface diff. It is a convenience for following up on a diff, not a general way to name any symbol in the tree.

The rest of the query surface

Every one of them takes --json, and every one is read-only — they are served from the index attached to your current commit. On a complete clone that is entirely local. On a partial clone that omitted symbol attachments, a query may fetch the object it needs from the origin; if the origin is unreachable it degrades to an empty result rather than failing, and tovio fetch --complete restores a definitive answer.

For agents

The SDK and MCP expose the same graph — symbolContext / symbol_context, plus symbol relations, search, and change impact — so an agent can orient around a symbol before editing rather than reading the repository. The reads are scope-gated: an agent whose token cannot read a path does not see its symbols either.

If a query finds nothing

An empty result is the normal, non-error outcome. It means one of: the moniker is not in the index, the file's language has no backend, the file is policy-protected and you are not a recipient, or nothing has been indexed yet. All of these print an empty result and exit 0 — the layer is advisory and reports rather than fails.

You may see TVO-SEM-001 (no language indexer for a path) and TVO-SEM-002 (the cached shard was built by a different indexer version) referenced in the error catalog. They are two distinct codes, not one, and both are reserved: they are specified but not emitted by any shipped build, so you will not see either in practice today. The conditions they describe are real and are handled silently — an unsupported language degrades to a text diff, and a stale shard is simply re-extracted.