Tool

import

Bring another repository, folder, bucket or report into the index. Once it’s imported, you can search, read and query it with the same tools you use on your own code, at its own address.

Choose the source

The address you pass decides what happens. Repositories, buckets and folders are indexed in the background. Reports are read straight away.

A report adds findings to files that are already indexed. It doesn’t run the scanner or the tests. Importing the same report again replaces its earlier findings.

A private GitHub repository needs GITHUB_TOKEN or GH_TOKEN set in the host’s environment. Imported git repositories refresh themselves from their remote by default, and imported folders are watched live. To refresh a repository now, import it again: only the changed files are re-indexed.

Wait for indexing

A repository, bucket or folder import returns as soon as it’s registered. Files become searchable as they’re indexed. Until then, an empty result doesn’t mean the code isn’t there.

The response gives you an operation ID and the commands to wait on it. rql monitor --target <id> blocks until the import reaches the stage you ask for: --until indexed for reading and structure, --until searchable for search by meaning. It also works after the import has finished. A plain rql monitor --until searchable without --target is refused; --until idle waits for the whole host instead.

Analysis depth

New imports use links analysis. Paths resolve: imports, document links and path-shaped references. Resolving names across files, such as a call to the method it names, needs full analysis. It costs more indexing work. Set it with rql import <uri> --analysis full; the MCP tool has no option for it.

Example: import a sibling service

Terminal

rql import ../billing-service

Output

Import started: local:///…/billing-service
Operation: 3b960b0f-1e14-4499-8a27-e86629e2b4a0
Scope: 1 file — indexing in the background; files become queryable as they land.

Wait for this import:
  Structural queries: rql monitor --target 3b960b0f1e1444998a27e86629e2b4a0 --until indexed --timeout 35m
  Semantic search:    rql monitor --target 3b960b0f1e1444998a27e86629e2b4a0 --until searchable --timeout 35m
  All work settled:   rql monitor --target 3b960b0f1e1444998a27e86629e2b4a0 --until complete --timeout 35m
These waits also work after completion; unresolved failures exit 1. --until idle waits for the whole host.
Track progress: SELECT state, ready_percent, indexed, total FROM Operations WHERE id = '3b960b0f-1e14-4499-8a27-e86629e2b4a0'; -- zero rows later = aged out; monitor still answers

Terminal

rql monitor --target 3b960b0f1e1444998a27e86629e2b4a0 --until searchable --timeout 5m

Output

import:local:///…/billing-service indexed — operation 3b960b0f1e1444998a27e86629e2b4a0
import:local:///…/billing-service searchable — operation 3b960b0f1e1444998a27e86629e2b4a0

Terminal

rql read "local:///**/billing-service/** => structure"

Output

RefundService.cs | RefundService | RefundInvoice | 13 ln, ~0.1k tok

addresses: #symbol=<name>
Billing
  +class RefundService
    +decimal RefundInvoice(string invoiceId, decimal amount)

• The import’s address. The folder has no git remote, so it answers at local:/// followed by its absolute path, shortened here with …. A glob such as local:///**/billing-service/** reaches it without typing the whole path.
• An operation ID and ready-made waits. The import returns before indexing finishes. The monitor command blocks, prints each stage as it’s reached, and exits 0 when the import is searchable.
• The same tools on imported code. read returns the imported file’s structure exactly as it would for your own code.

Remove an import

Through MCP, put - in front of the address: -github://owner/repo. In the terminal, use rql import remove <uri> or rql unimport <uri>. Either one deletes the indexed records and the mount. Files on disk, including a managed clone, are left in place. Report findings aren’t removed this way; re-import the report to replace them.

Without signing in, you can import up to two repositories. rql account login lifts the limit.

Parameters

Further reference

In the installed manual: help:///tools/import.md, help:///commands/import.md and help:///commands/monitor.md.