Tool
read
Read a file, a symbol, or a group of files at the level of detail your question needs.
Once you know where to look, read retrieves that part of the index. You can ask for a method body, the declarations in a directory, or a view of changes to a particular function. The address selects the source; the view selects what you learn about it.
Start with an address
An address can name one file or match many. A fragment narrows it to a symbol or line range. You can combine those choices: a glob can select service classes across a project, then a symbol fragment can select a method from each class. Addressing explains the grammar.
Let the response size choose the detail
Without an explicit view, RepoQL returns the richest representation that fits the token budget. A small file may fit in full. A larger selection may return declarations, clipped content, or headlines. Check what representation came back before assuming you have read the complete source.
If the response is too shallow, narrow the address or increase the budget. Asking for one method often provides more useful detail than giving a larger budget to an entire directory.
Choose a view for a specific question
Add a modifier after the address to ask for a particular view. structure shows declarations without bodies. history shows relevant commits. references shows indexed relationships such as calls, imports, and document links.
Text search and meaning search serve different questions. grep finds literal text, regex finds a text pattern, and find finds relevant passages within the selected files. similar compares stored embeddings with a seed file; it can suggest related tests, but it cannot prove test coverage.
Example: inspect a project before reading its files
Terminal
rql read "file:///src/cloud/website/** => tree: folders" --token-budget 800This returns the website’s folder layout. Select one directory for a closer read, or use tree: headlines to see descriptions alongside filenames.
Parameters and views
| MCP parameter | Use |
|---|---|
| uriGlob | Required. One address, a glob, or several addresses separated by semicolons. A trailing modifier applies to the selection. |
| tokenBudget | Optional. Maximum rendered response size. |
| View | What it returns |
|---|---|
| content | Source with line numbers. Resolves supported @ references in documents. |
| content: literal | Source with references left untouched. Use this when preparing an edit. |
| content: preview | A reference manifest and estimated assembly cost. |
| structure | Declarations, signatures, or headings. |
| headline | A short description for each file. |
| tree: folders / files / headlines | The directory layout with the requested level of detail. |
| find: keywords | Passages related to the supplied terms. |
| grep: text / regex: pattern | Matching lines. Lowercase grep is case-insensitive; uppercase makes it case-sensitive. |
| similar: seed-uri | Selected files ranked by stored-vector similarity to the seed. |
| references: destination-glob | Indexed reference edges, optionally filtered by destination. |
| history / history: topic | Git commits affecting the selected files or symbols, optionally ranked by topic. |
| blame | Git attribution for lines in the selection. |
| changes | Working-copy changes, grouped by staged, unstaged, and untracked. |
| where / where: remote | Disk paths or remote source URLs. |
| concepts | Repository concepts relevant to the selection. |
| question: question | A cloud-generated answer about the selected content, with citations. |
| lint: errors / warnings | Imported or generated diagnostics; warnings includes errors. |
| coverage: uncovered / content | Coverage gaps or source annotated with execution counts, when coverage data is available. |
Available relationships and structure depend on the file format and analysis settings. Lint and coverage views report existing annotations; they do not run a linter or a test suite. Tree requests that need a larger budget report that requirement.
Further reference
In the installed manual: help:///tools/read.md, help:///tools/read-transclusion.md.