Tool

execute

Run a short JavaScript script that calls RepoQL for you. Use it when each step depends on the one before: query for rows, read what they point at, and return only the answer.

If you	Use
Need loops, branching or several steps in one call	`execute`
Can answer with one SQL statement	`query`
Already know the address you want	`read`

How a script runs

The script runs inside RepoQL, in a QuickJS sandbox compiled to WebAssembly. It isn’t Node.js or a browser, so it reaches files and tools only through the APIs below. Time and memory limits bound every run.

The last expression is the result. End with the value you want back. Arrays and objects come back as tables.
Calls are synchronous. Every repoql.* and mcp.* call returns its result directly, so you don’t need await.
No top-level return or await. Both are syntax errors. Wrap code in (() => { … })() if you want return.
A promise at the end is resolved. That is how you use modules: end with import("yaml").then(yaml => …).

What a script can call

Call	What it does
`repoql.query(sql)`	Runs SQL, as `query` does, and returns the rows.
`repoql.read(address, { budget })`	Reads an address, as `read` does. Returns `{ content, representation, tokensUsed }`.
`repoql.write(path, content)`	Writes a file inside your repository.
`repoql.delete(path)`	Deletes a file. By default only under `.repoql/tmp/`.
`repoql.graphviz(dot)`	Renders a Graphviz diagram as SVG.
`repoql.svgToPng(svg, width)`	Converts SVG to a PNG, as base64.
`mcp.servers()` · `mcp.tools(server)` · `mcp.describe(server, tool)`	Lists your connected MCP servers and their tools.
`mcp.server.tool(args)`	Calls an approved MCP tool and returns its result parsed into objects or rows.
`import(name)`	Loads a built-in module, such as `yaml`, `diff` or `semver`.

Two more calls depend on the host. repoql.ffmpeg needs ffmpeg and ffprobe installed. repoql.pandoc needs an optional module that released builds don’t include. Don’t rely on either being available.

What comes back

This script answers “which methods touch CLI token revocation?” It lists every method with SQL, reads each one’s body, and keeps those that mention RevokeCliTokens.

Terminal

rql execute <<'EOF'
const methods = repoql.query(`
  SELECT file, qualified_name FROM Functions
  WHERE matches_glob(uri, 'src/**') AND function_kind = 'method'
  ORDER BY qualified_name`);

methods
  .map(m => ({
    method: m.qualified_name,
    body: repoql.read(`${m.file}#symbol=${m.qualified_name}`, { budget: 200 }).content
  }))
  .filter(m => m.body.includes("RevokeCliTokens"))
  .map(m => m.method);
EOF

Output

value
Demo.Auth.SignOut.Execute
Demo.Auth.TokenService.RevokeCliTokens

Only the answer. The method bodies stayed inside the sandbox. You get the two names, not every body.
The last expression became the result. An array of strings comes back as a one-column table.
The script came from standard input. You can also pass it as the first argument or with --file.

Scopes

Scopes limit what a script can touch. By default a script can read file://, help://, github:// and concept:// addresses. It can write anywhere inside the repository, and no path can escape the repository root. It can delete only under .repoql/tmp/.

Change them with rql config set sandbox.read_scopes "<patterns>", and the same for sandbox.write_scopes and sandbox.delete_scopes. rql config read sandbox.read_scopes shows the current value and where it came from. A new value replaces the default rather than adding to it, so list every pattern you still need.

MCP calls follow the same approval rules as calls from SQL, and they can reach external services.

Parameters

MCP · CLI	Meaning
`code` · first argument	Required. The JavaScript to run. On the command line you can pipe it in instead.
`intent` · `--intent`	What you want the script to achieve, in plain words. It labels the result.
`tokenBudget` · `--token-budget`	The most tokens the response may use. The default is 15,000.
`timeout` · `--timeout`	Stop the script after this many milliseconds. The default is five minutes.
CLI only: `--file`	Read the script from a file.
CLI only: `--json` · `--jsonl`	Structured output. `--json` gives one document, including a structured failure if the script throws. `--jsonl` gives one line per result record.

Further reference

In the installed manual: help:///tools/execute.md and help:///commands/execute.md.