Tool

explain

Get a written answer to a question about your code, with the evidence it rests on. explain searches, reads the relevant source and writes an answer that cites the files and declarations behind it.

Ask a bounded question

A question names one behaviour: “What happens to a user’s CLI tokens when they sign out?” A question like “Explain everything about authentication” has no edge, so the answer won’t either.

Keywords are the names you already know, such as SignOut RevokeCliTokens. They steer the first search. Through MCP they are required. The CLI can infer them from the question, but your own names usually give a sharper answer. If you don’t know the names yet, run explore or discover_vocabulary first.

Scope the investigation

The scope is an address, such as src/auth/**. The first search and the folder overview stay inside it, and your team’s concepts for that area join the evidence. Scope to the part of the code your question is about.

The scope is a starting point, not a wall. While it writes the answer, explain can read further files it needs. A scope that is too narrow can still miss a dependency that changes the answer. One that is too broad can spend effort on the wrong implementation.

Several scoped questions beat one broad one. They are independent, so an agent can run them in parallel.

What comes back

Terminal

rql explain "What happens to a user's CLI tokens when they sign out?" \
  --keywords "SignOut RevokeCliTokens Wristband" --uri-glob "src/auth/**" --token-budget 800

Output

## What happens to a user's CLI tokens when they sign out?

<Answer>
When a user signs out, their CLI tokens are revoked. `SignOut.Execute(userId)` first ends all of the user's Wristbands (`wristbands.EndAll(userId)`) and then calls `tokens.RevokeCliTokens(userId)`, so sign-out revokes the CLI tokens in addition to ending sessions. This matches the recorded repository rule ("Signing a user out also revokes their CLI tokens"), which exists because the CLI signs in with its own token that previously kept working after sign-out.

I verified the call in `SignOut.Execute`; I did not inspect the body of `TokenService.RevokeCliTokens`, so the exact revocation mechanics (e.g., which tokens are considered "CLI tokens") are not established here.
</Answer>
<Evidence>
- file:///src/auth/SignOut.cs#symbol=SignOut.Execute (lines 7–11): `wristbands.EndAll(userId); tokens.RevokeCliTokens(userId);`
- concept:///rule/auth/SignOutRevokesCliTokens.md — invariant: "Signing a user out also revokes their CLI tokens."
</Evidence>

• An answer in plain prose, naming the declarations it relied on.
• Evidence as addresses you can pass to read. Here, one method and one of your team’s concepts.
• A footer with the tokens used and the time taken. This answer took about 15 seconds.

Check the claims that matter

An answer is a synthesis. It can miss a path, misread a condition or join two things that aren’t the same. Read the cited code before you change behaviour because of it.

The example shows why. The answer says it didn’t inspect TokenService.RevokeCliTokens. But SignOut calls RevokeCliTokens on a TokenStore, not on TokenService. Reading the one cited method shows this in seconds.

Cost and requirements

explain uses cloud inference, so you need to be signed in. Without it, the call fails and tells you to run rql account login. The source it reads is sent to the inference service. Your data explains how that is processed.

The token budget caps the length of the answer, not how much source is read to write it.

Parameters

Further reference

In the installed manual: help:///commands/explain.md.