Getting oriented

Addressing

A RepoQL address describes where to look, which part of the source to select, and what view to return.

You can start with a repository or directory and narrow the selection as you learn more. The same grammar works for workspace files, imported repositories, and the installed manual. That lets an investigation move between sources without learning a different way to select each one.

Build an address in three parts

file:///src/**/*.csScope: C# files below src#symbol=*ServiceSelection: matching service symbols=> structureView: declarations without bodies

The scope is enough for a basic read. Add a fragment when you want a symbol or line range. Add a read modifier when you want a particular view. Without a modifier, the response budget determines how much detail comes back.

Choose the source before the detail

file:/// refers to the current workspace root. An imported repository has its own identity, such as github://dotnet/roslyn/. help:/// addresses the installed manual and concept:/// addresses repository concepts.

Globs select several sources at once. A single * matches within a path segment; ** can cross directories. Separate addresses with a semicolon to combine selections, or add an exclusion to remove a part of the scope.

Select a symbol or a line range

A symbol fragment selects a parsed declaration by name. This is useful for a method whose line numbers change during editing. The name must still resolve within the file or glob you selected; renaming or moving it outside that scope requires a new address.

Line fragments select numbered source lines and work when you already have a location from an error or review. They are one-based, and a range includes both endpoints. Unlike a symbol selection, a line range can point at different text after an edit.

Ask for the view you need

Append => structure to inspect declarations, => history to inspect relevant commits, or => references to inspect recorded relationships. One trailing modifier applies to the selected addresses. The read reference describes the available views and their limits.

Example: inspect the website source tree

Terminal

rql read "file:///src/cloud/website/** => tree: folders" --token-budget 2000

Quote addresses in a shell so glob characters, semicolons, and > reach RepoQL unchanged. An MCP call passes the same address as a string.

Syntax reference

Syntax	Meaning
file:///path	Workspace-relative source address.
github://owner/repo/path	A file in an imported GitHub repository.
help:///path	A page in the installed manual.
concept:///path	A repository concept.
* · **	Match within one segment, or across directories.
? · [a-z] · {a,b}	One character, a character range, or alternatives.
;	Combine address patterns.
!pattern	Exclude matches from the selection.
#symbol=Name	Select a parsed symbol; qualified names and wildcard patterns are supported.
#symbol=Name.* / Name.**	Select direct members or descendants.
#line=42 / #line=42,60	Select one line or an inclusive range.
=> modifier: argument	Request a read view with an optional argument.

Further reference

In the installed manual: help:///tools/uri-patterns.md, help:///tools/glob-patterns.csv, help:///tools/read.md.