Tool

explore

Find the code behind a behaviour, even when you don’t know what it’s called. explore searches by words and by meaning, and returns the most relevant files and declarations, ranked, with enough context to choose what to read next.

If you	Use
Can describe a behaviour but don’t know where it lives	`explore`
Already know the file or declaration	`read`
Get weak results because the code uses names you don’t know	`discover_vocabulary` first
Want a count, a list or a comparison	`query`

Ask with keywords and a question

Keywords name the subject: a feature, a class name or a short phrase, such as revoke tokens. They are matched by spelling and by meaning.

A question says what you want to learn about it: “What happens to a user’s CLI tokens when they sign out?” When reranking is available, results are ordered by how well they answer the question, not only by how well they match the words.

Scope the search

The scope is an address that limits where to look. src/** searches your repository’s src folder; github://acme/platform/** searches an imported repository. Scope to the project your question is about: searching everything can return plausible answers from the wrong one.

What comes back

Terminal

rql explore "revoke tokens" --question "What happens to a user's CLI tokens when they sign out?" \
  --uri-glob "src/**" --token-budget 600

Output

file:///src/auth/
 95% /TokenService.cs
  TokenService | Issue, RevokeCliTokens, Refresh | 15 ln, ~0.1k tok
  addresses: #symbol=<name>
  Demo.Auth
    // Issues and revokes the tokens the CLI signs in with.
    +class TokenService
      // Issues a CLI token for a user.
      +string Issue(string userId)
      // Revokes every CLI token a user holds.
      +RevokeCliTokens(string userId)
      // Exchanges a token that is about to expire for a fresh one.
      +string Refresh(string token)

 44% /SignOut.cs
  SignOut | Execute | 13 ln, ~0.1k tok

Relevant concepts:
concept:///rule/auth/SignOutRevokesCliTokens.md  file:///src/auth/**
  Signing a user out also revokes their CLI tokens.

Ranked matches. Each file has a relevance score and a one-line headline. The strongest also show their declarations, so you can often pick the method to read without opening the file.
Addresses to read next. Pass a match to read, adding #symbol= for one declaration: src/auth/TokenService.cs#symbol=TokenService.RevokeCliTokens.
Relevant concepts. Your team’s concepts that cover the files shown, each at most once per session.
A footer with the tokens used and the index’s readiness.

Treat matches as leads. A score says how well a file matches the search. It doesn’t prove the file implements the behaviour, or that the search found every file that does. Read the code before you rely on it. And if the footer says indexing isn’t finished, an empty result isn’t proof of absence.

Budget and breadth

The token budget caps the response. A small budget returns mostly headlines; a larger one leaves room for declarations and snippets. Narrowing the scope makes the same budget go further.

Breadth sets how the budget is spread: lower values give more detail on the strongest matches, higher values survey more of them. It isn’t a result count. Leave it on automatic unless you need to steer it.

Parameters

MCP · CLI	Meaning
`keywords` · first argument	Required. Names, concepts or short phrases to search for.
`question` · `--question`	What you want to learn, as a full sentence. Orders results by how well they answer it.
`uriGlob` · `--uri-glob`	Where to search, as an address. A pattern without a scheme means your repository.
`tokenBudget` · `--token-budget`	The most tokens the response may use.
`breadth` · `--breadth`	How widely detail is spread across matches. `0`, the default, sets it from the match strengths.
`uplink` · `--uplink`	Search a team’s uplink instead of your local repository.
CLI only: `--json` · `--jsonl`	Structured matches, as one JSON document or one line per match.

Further reference

In the installed manual: help:///tools/explore.md and help:///commands/explore.md.