Workspaces
Navigate tools
nace locate, nace read-file and nace run-sql are the tools the document service's own search agent works with, for your own code agent: locate names the pages and tables that hold a piece of information, read-file reads them and run-sql queries the tables. Each answers at once, from the files in a workspace that are ingested, and prints what the ndi CLI prints for the same call. They are free; locates are limited to 150 per account every 10 minutes, and file reads and SQL queries together to 600. Past that, a command exits 1 with 429 rate_limited, and stderr says when to run it again.
To give a code agent the loop that uses them, install the agent skill. See Navigate tools for the routes.
A call that times out keeps running on the document service, so each command retries under the same key for up to 15 minutes and prints the first call's answer. The first locate after a workspace's files change can take a minute or more.
Locate
nace locate "monthly base rent in the first lease year" \
--question "What is the monthly base rent for unit 12 in the first lease year?"
# Located for: monthly base rent in the first lease year
#
# [1] leases/unit-12.pdf — page 2 (agreement_1; score 1.00) → `nace read-file leases/unit-12.pdf --pages 2`
# # Article 3. Rent and security deposit 3.1 Base Rent. Tenant will pay Base Rent of $9,600.00 per month ...
# ...
nace locate "security deposit amount" # the same run: leaves out what it already showed and you readnace locate NEED prints the answer's text as the document service writes it: each page or span of lines, best first, with its score, the read that opens it and its text (the best pages in full, the rest by their opening lines), then the tables it rated, with their sql names and the columns to look at. Every command it names is written as nace runs it (nace read-file ..., nace run-sql), so it runs as printed; the response's text names the document service's own CLI (ndi read-file ...). See Locate information for the response; --json prints it whole.
When the answer needs every file of a kind, such as a total over each invoice, nace locate --all "invoices from Acme in 2026" rates every file of that kind and lists the members by path, to read each. It is not a search: to find a document or a value, locate it without --all. When the budget ran out before rating every likely file, it says so: narrow the need to a folder, kind or period.
The run. nace keeps a task's run in a file beside the config file (under locate/ in ~/.nace), one per workspace: its question, every piece a locate offered and every read nace read-file finished. A later locate sends them back, so it leaves out what you were shown and what you read, and says how many it left out.
--questionstarts a run; a different question starts a new one, and a run that so far only read takes it.--pointernames every page by its opening lines only. A task's later locates pass it, so page text does not pile up; read the pages you want.--freshstarts over on the same question, unless--questiongives a new one. A run unused for 6 hours is over.- Set
NACE_LOCATE_SESSIONto a name per task to keep two tasks in one workspace apart. - Over 1,000 offered or read pieces, a locate exits
1with422 invalid_request: start a--freshrun.
| Flag | What it does |
|---|---|
--workspace ID | The workspace to locate in. See Choose a workspace. |
-k N | How many pages to name, at most 24 (default 12). |
--all | The need names a kind of file and every one is wanted (each invoice, every statement): the navigator rates each file of that kind and lists the members. |
--question QUESTION | The task's whole question. Default: the run's, else the need. |
--path-prefix, --prefix PATH | Only files under this folder. |
--path P | Only this file, by its path. Repeatable; with --path-prefix, both. |
--pointer | Name every page by its opening lines only (default: the best pages in full). A task's later locates pass it, so page text does not pile up. |
--fresh | Start a new run on the same question: forget what earlier locates offered and what was read. |
Read a file
nace read-file leases/unit-12.pdf --pages 2
nace read-file reports/notes.md --lines 120-180
nace read-file finance/tb.xlsx --component "Trial Balance" --lines 1-24
nace read-file a.pdf b.pdf --pages 1 # each under a `==> path <==` headernace read-file PATH prints the file's text on stdout, and one footer line on stderr: read <path>, then, when they apply, | lines <a>-<b> of <n>, | pages <ranges>, | components: <names>, | omitted: <names> and | TRUNCATED (raise --max-chars, or scope with --component/--pages). When a span of lines starts inside a table, the table's header comes first, as [table lines <first>-<last>] <first>: <header>. Several paths are read together and printed in order, each under ==> <path> <==, with a blank line between; one that fails prints error: <path>: <status> [<code>] <message> on stderr, the rest still print, and the command exits 1. With --json, several paths print one JSON array of the reads that succeeded. A file that isn't ingested yet exits 1 with 409 file_not_ingested. See Read a file.
A read that finished is added to the workspace's locate run, so the next nace locate leaves it out.
| Flag | What it does |
|---|---|
--workspace ID | The workspace to read from. See Choose a workspace. |
--component COMPONENT | One tab or section. |
--pages SPEC | 1-based pages, such as 3 or 1-5,8. Not for spreadsheets. |
--lines A-B | Only these lines of what the read returns: A-B, A- (to the end), -B or A, 1-based and inclusive. It reaches text past --max-chars; the footer gives the line count. |
--max-chars N | The most characters to return. Above 1,000,000 it is sent as 1,000,000. |
Run a SQL query
nace run-sql "SELECT \"Account name\", Debit FROM tb_2026_09_trial_balance WHERE Debit > 10000"
# result table res_45eb9a76727d — 4 rows
# Account name (VARCHAR) | Debit (DOUBLE)
# {"Account name": "Cash - Fernhollow Bank operating", "Debit": "61422.18"}
# ...
# note: 'res_45eb9a76727d' is a registered table — join or page it in your next run-sql call.
# sources: finance/tb.xlsx
nace run-sql "SELECT sum(Debit) FROM res_45eb9a76727d"nace run-sql SQL runs one read-only SELECT (DuckDB dialect) over the workspace's tables and prints the result as result table <handle> — <n> rows, with , showing only the first <k> (preview cap; the full result is behind the handle) when the preview is cut and (duplicate — served from the stored result) when an identical query answered it; then the columns with their types, one JSON object per preview row, a note that the handle is a table your next query may read, and sources:. Table names come from nace locate; a query naming an unknown table exits 1 with 422 invalid_request, and the message lists the tables. --json adds a download link to the whole result as a Parquet file. See Run a SQL query.
| Flag | What it does |
|---|---|
--workspace ID | The workspace to query. See Choose a workspace. |
Agent skill
nace skill install --agent claude-code # write both skills to ~/.claude/skills
nace skill drex-search # print one
nace skill drex-workspacenace skill [NAME] prints an agent skill that ships with the CLI, so it always matches the commands you have installed. NAME is drex-search, the default: the locate, read-file and run-sql loop, and nothing else; or drex-workspace: create a workspace, upload and ingest, check it, and save it for later sessions. Neither sends a request or needs a key. The skill's frontmatter carries the CLI's version as metadata.nace-cli-version.
nace skill install [NAME...] --agent AGENT writes each skill, both by default, to <NAME>/SKILL.md in the agent's skills folder, and prints wrote <path> on stderr, or up to date: <path> when the file already matches. Run it again after you upgrade the CLI. See Agent skills for each agent's folder.
| Flag | What it does |
|---|---|
--agent {claude-code,codex,cursor,pi,hermes,agents} | Required. The agent whose skills folder to write to; agents is the Agent Skills folder, ~/.agents/skills, that other agents read. |
--project | Write to the project's folder, under the current directory, instead of your user folder. |
When a copy the CLI would write, in an agent's user folder or the current directory's project folder, is older than the CLI, nace locate, nace read-file and nace run-sql print one line on stderr naming it and the nace skill install command that updates it. Until some agent has both skills installed, nace workspace-create and nace workspace-use print one line on stderr suggesting nace skill install --agent AGENT.