Getting oriented
Addressing
Every RepoQL tool takes an address: one string that says where to look, what to pick out and how to show it. You start wide and narrow down as you learn, without switching tools.
file:///src/auth/*.cs#symbol=TokenService.Refresh => history
file:///src/auth/*.csWhere. The C# files in src/auth/.
#symbol=TokenService.RefreshWhat. One method in them.
=> historyHow. The commits that wrote its current lines.
Only the first part is required. Leave out the second to take whole files. Leave out the third, and RepoQL returns the richest view that fits your token budget.
Narrow as you learn
An investigation usually runs from the shape of a codebase down to one piece of it. Each step is the same tool with a narrower address:
- See the shape.
file:///** => tree: folderslists the folders and what kinds of files they hold. - Read the signatures.
file:///src/auth/*.cs => structureshows every declaration in those files, without the bodies. - Read one method.
file:///src/auth/TokenService.cs#symbol=TokenService.Refreshreturns just that method.
Terminal
rql read "file:///** => tree: folders" --token-budget 1000
rql read "file:///src/auth/*.cs => structure" --token-budget 1500
rql read "file:///src/auth/TokenService.cs#symbol=TokenService.Refresh" --token-budget 800Your agent makes the same calls through MCP, passing each address as a string. The rest of this page covers each part in turn.
Where: schemes
The scheme says which tree to look in. Every tree answers to the same patterns.
| Scheme | Addresses |
|---|---|
file:/// | The repository your RepoQL host serves. |
github://owner/repo/git://host/path/s3://bucket/prefix/local:///path/ | Sources you have imported. |
worktree://name/ | A git worktree of your repository: the same paths as file:///, with the worktree’s content. It’s searched only when you name it. |
concept:///vocabulary:/// | Your repository’s concepts and vocabulary. |
help:/// | RepoQL’s own manual. |
A path with no scheme, such as src/auth/**, means file:///. A path that starts with a wildcard, such as **/*.md, matches under every scheme.
Which files: globs
| Pattern | Matches | Example |
|---|---|---|
* | Anything within one folder level | src/auth/*.cs |
** | Any number of folder levels | src/**/*.cs |
? | One character | src/v?/** |
[0-9] | One character from a set | log[0-9].txt |
{a,b} | Any of the alternatives | src/{auth,billing}/** |
; | Also this pattern | src/**;docs/** |
! | Except this pattern | **/*.cs;!**/tests/** |
**must be a whole path segment:src/**/test*works,src/**testdoesn’t.- An exclusion removes matches from every pattern you included, not only the one before it.
- Matching ignores case.
- For a file whose name contains
*or[, percent-encode the character:app/%5Bid%5D.tsx.
Which part: fragments
A fragment, after #, picks part of each matched file.
| Fragment | Selects |
|---|---|
#symbol=TokenService.Refresh | One declaration, by name. |
#symbol=TokenService.*#symbol=TokenService.** | A type’s direct members, or everything inside it at any depth. |
#symbol=TokenService.{Issue,Refresh} | Several named members. |
#symbol=*Token* | Every declaration whose fully qualified name matches, so Demo.Auth.TokenService.Refresh matches too. |
#kind=method | Declarations of one kind. #visibility=, #extends= and #implements= filter the same way. |
#line=7,11 | Lines 7 to 11, both included. #line=7 is one line. |
#token-refresh | A Markdown heading’s section, by its anchor. |
#/auth/refreshWindowMinutes | One value in a JSON or YAML file, as a JSON Pointer. |
A literal symbol name is case-sensitive; a wildcard matches either case. Join fragment parts with &: #symbol=*Token*&kind=method is the methods whose names contain Token.
Prefer a symbol to a line range. A symbol address follows its declaration as lines move during editing. A line range is right for a location you were given, such as an error or a review comment, but it can point at different text after an edit.
How to show it: views
A view, after =>, says what to return. Some take a parameter after a colon: => grep: revoke. One view applies to the whole address.
| To | Views |
|---|---|
| Read | content, structure, headlines, tree: folders · files · headlines |
| Search inside the matches | grep: text, regex: pattern, find: keywords, similar: address |
| See the history | history, blame, changes |
| Understand | concepts, references, question: text |
| Check | lint, coverage |
| Locate | where, for paths on disk or GitHub links |
Without a view, you get full content when it fits your budget. When it doesn’t, RepoQL falls back to signatures, then a clipped excerpt, then a one-line headline. The read reference covers each view.
Many places at once
Join specific addresses with ; to fetch them in one call:
rql read "file:///src/auth/SignOut.cs#symbol=SignOut.Execute;file:///docs/auth.md#sign-out" --token-budget 800Every match shares the token budget, so ten matches at a budget of 2,000 get about 200 tokens each. A wide glob therefore comes back as headlines. To get depth, narrow the address or raise the budget.
Where addresses work
readtakes an address.exploretakes one as its scope, so a search can be limited tofile:///src/auth/**.- A concept’s
relevanceandverificationare addresses. - In SQL,
glob_filesandmatches_globtake the same patterns.
In a shell, quote the address so that *, ; and > reach RepoQL unchanged.
Further reference
In the installed manual: help:///tools/uri-patterns.md for the full grammar, help:///tools/glob-patterns.csv for every glob form, and help:///tools/read.md for the views.