Vera works best when you describe what the code does. This page covers how to phrase queries, how to narrow results, and which command fits which question. The full list of flags is in features.
| You want to know | Use |
|---|---|
| How or where something works | vera search "how expired sessions are cleaned up" |
| Where a named symbol is defined | vera structural definitions SessionStore |
| Who calls a function, or what it calls | vera references cleanup_sessions / --callees |
| Every route, env var read, or implementation | vera structural routes / env / impls <symbol> |
| An exact string or regex | vera grep "SESSION_TTL" |
| What a codebase looks like overall | vera overview |
| Something in the docs | vera search "deploying behind a proxy" --scope docs |
| Code in your project and an indexed dependency tree | vera search "retry backoff" --also ~/.cargo/registry/src |
Good queries say what the code does:
vera search "JWT token validation"
vera search "retry failed requests with backoff"
vera search "database connection pooling"
vera search "where uploaded files are written to disk"Single generic words match too much to rank well:
vera search "auth" # which part of auth?
vera search "utils"
vera search "handler"If you know the name, search for it. Keyword search handles exact identifiers, file names, and config keys directly:
vera search "AuthMiddleware"
vera search "max_connections"For a definition, vera structural definitions AuthMiddleware is more direct: it returns the declaration instead of every place the name appears.
Try these in order:
-
Rephrase in two or three ways at once. Vera merges the results, so one call covers several angles:
vera search "OAuth token refresh" "JWT expiry handling" "auth middleware"
-
Add your goal with
--intentwhen the query is short or ambiguous:vera search "config" --intent "find where database connection strings are loaded from environment variables"
-
Narrow with filters (next section).
-
Use
--deepfor questions whose answer spans several files. See deep search.
If the top hit is a place that uses the symbol rather than defines it, take the name from that hit and run vera structural definitions <name> instead of trying more phrasings.
Add filters one at a time:
vera search "error handling" --lang rust
vera search "error handling" --lang rust --type function
vera search "routes" --path "src/**/*.ts" --path "tests/**/*.ts"
vera search "mod loader" --scope runtime --include-generated
vera search "token validation" --changed--pathis relative to the repository root. A bare directory such as--path src/apimatches everything below it.--type functionalso matches methods, and the reverse.--scope docssearches documentation;--scope runtimesearches extracted or bundled app code;--scope alllets every content class except generated files match, as no--scopedoes, and source code still ranks first.--changedlimits the search to modified, staged, and untracked files;--base <rev>to files changed since the merge base with<rev>(a branch diff);--since <rev>to files changed since<rev>.
Vera ranks source code above docs and tests; use --scope to search only one kind of file. Generated files such as minified bundles are left out of results unless you pass --include-generated. Directories such as dist, build, and node_modules are not indexed at all by default; see Configuration to change the exclusions.
vera references matches calls by name. If two classes both define get, their callers come back together. When the calls use at least two different receiver names, the output lists them:
vera references get # all calls to anything named get, with receiver counts
vera references get --receiver app # only calls written as app.get(...)
vera references get --path src --path 'tests/**/*.rs' # callers matching either pathCalls with no receiver, such as a plain get(), do not match any --receiver value.
Use vera grep for exact text or regex in indexed files. It shares vera search's filters and git scopes:
vera grep "EMBEDDING_MODEL_BASE_URL"
vera grep "TODO\(" -i
vera grep "queryClient|invalidateQueries" --path "frontend/src/**"It uses Rust regex syntax: | is alternation and \| matches a literal pipe. If none of your --path patterns match an indexed file, Vera suggests a pattern that would.
Use rg when you need to:
- search files that are not indexed (dependencies, ignored or generated trees)
- count occurrences
- find files by name
- prepare a find-and-replace
If Vera warns that the index is stale, or results miss code you just wrote:
vera update . # once
vera watch . # continuously while you workIf a file never shows up, vera explain-path path/to/file tells you why it is not indexed. More fixes are in troubleshooting.
Each result is labeled with its path, line range, symbol type, and name:
```src/flask/cli.py:698-763 function:load_dotenv
Results are in ranked order; trust the order. When JSON output includes a score, it only ranks results within that query and cannot be compared across queries. Large symbols are split into parts and labeled name (part N); in JSON, symbol_name holds the bare name and part_index the part.