Tool

read

Get exactly the part of your code you ask for: a file, one declaration, a folder’s layout, or a view such as its history or matching lines. read returns the most detail that fits your token budget.

If you	Use
Know the file, declaration or folder you want	`read`
Don’t know where the code lives yet	`explore` first, then `read` the matches
Want a count, a list or a comparison across many files	`query`
Want an explained answer drawn from across the repository	`explain`

Name what you want

You tell read what to fetch with an address. It can be one file, a glob that matches many, or one declaration inside a file, such as src/auth/TokenService.cs#symbol=TokenService.RevokeCliTokens. The Addressing page explains the whole grammar. This page covers what read does with the address.

How read chooses detail

Without a view, you get the richest form that fits the budget. RepoQL tries each form in turn:

Content. The full text.
Structure. Declarations and signatures, without bodies.
Clipped. The text, cut at a line boundary to fill the budget, with a note that it was cut.
Headline. One line per file.

All the matches share the budget. One file at a budget of 4,000 usually comes back in full. Hundreds of files at the same budget come back as headlines. To get more depth, narrow the address or raise the budget.

An address for part of a file, such as a symbol or a line range, never falls back to the whole file’s structure or headline. If a small budget returns nothing, raise it.

Check what came back. A headline or a clipped excerpt is not the whole source. The footer tells you what a fuller read would cost, so you can decide whether to ask again. When you need line numbers, ask for => content.

What comes back

Terminal

rql read "src/auth/**" --token-budget 250

Output

base: file:///src/auth/
addresses: #symbol=<name>

--- SignOut.cs ---
namespace Demo.Auth;

/// <summary>Ends a user's sessions when they sign out.</summary>
public sealed class SignOut(WristbandStore wristbands, TokenStore tokens)
{
    /// <summary>Signs the user out: ends every Wristband and revokes their CLI tokens.</summary>
    public void Execute(string userId)
    {
        wristbands.EndAll(userId);
        tokens.RevokeCliTokens(userId);
    }
}

TokenService.cs | TokenService | Issue, RevokeCliTokens, Refresh | 15 ln, ~0.1k tok

A shared base. Paths are shown relative to file:///src/auth/. Add #symbol= and a name to any of them to read one declaration.
Full content where it fits. SignOut.cs fitted, so you see all of it.
A headline where it didn’t. TokenService.cs is reduced to its type, its methods and its size. Read it on its own, or raise the budget, to see the code.

Choose a view

Add => and a view after the address to ask a specific question about it. One view applies to the whole read. An explicit view is never replaced by a smaller form.

To	Views
Read the text	`content` gives full text with line numbers. `content: literal` leaves `@` references in documents untouched; use it before you edit. `content: preview` lists those references and what including them would cost.
See the shape	`structure` gives declarations without bodies. `headline` (or `headlines`) gives one line per file. `tree: folders`, `tree: files` and `tree: headlines` show the folder layout at three levels of detail.
Search inside the matches	`grep: text` finds literal text; all lowercase ignores case, any capital makes it match case exactly. `regex: pattern` finds a pattern. `find: keywords` finds passages by meaning. `similar: address` ranks the matches by likeness to another file, for example to find its tests.
See how it got here	`history` lists the commits that changed it; `history: topic` ranks them by relevance. `blame` shows which commit wrote each line. `changes` shows uncommitted work.
Understand it	`references` lists calls, imports and document links out of the matches; `references: address` keeps only those pointing at that address. `concepts` lists your team’s concepts that apply. `question: text` returns a generated answer with citations.
Check it	`lint` (or `lint: errors`, `lint: warnings`) lists diagnostics already recorded. `coverage` (or `coverage: uncovered`, `coverage: content`) shows imported test coverage. Neither runs a linter or your tests.
Locate it	`where` gives paths on disk and GitHub links; `where: local` and `where: remote` give one of them.

grep, regex, find, similar and question need their parameter after the colon.

Parameters

MCP · CLI	Meaning
`uriGlob` · first argument	Required. The address to read, optionally followed by `=>` and one view.
`tokenBudget` · `--token-budget`	The most tokens the response may use. On the command line you can also give it as a second argument.
`uplink` · `--uplink`	Read from a team’s uplink instead of your local repository.
CLI only: `--json` · `--jsonl`	Structured output, as one JSON document or one line per record.

Further reference

In the installed manual: help:///tools/read.md, help:///tools/read-transclusion.md, help:///tools/uri-patterns.md and help:///commands/read.md.