Workspaces

A workspace holds the files you upload, and what ingestion builds from them. Creating, reading, updating and deleting workspaces costs nothing and works at any balance. See Workspaces, and the API reference for every field.

Choose a workspace

nace workspace-use <workspace_id>   # save it for the commands that follow
# using workspace <workspace_id> (/Users/you/.nace/config.toml)
nace workspace                      # print the workspace commands use now
nace workspace-use --clear          # forget the saved workspace

Every command that works on one workspace takes --workspace ID: the workspace, file, ingestion and search commands below. Each except nace workspace-delete, which takes it only from the flag, picks the workspace in this order:

--workspace ID.
$NACE_WORKSPACE_ID.
The workspace nace workspace-use saved, as workspace_id in the config file.

With none of them, the command exits 2 before any request and says how to pick one: there is no default workspace. Create one with nace workspace-create.

nace upload, nace upload-grant and nace upload-session take --workspace ID too, but only the flag: without it, the file is uploaded to the server. So is a local file you pass as a tool's SOURCE.

nace workspace-use WORKSPACE_ID saves a workspace for the commands that follow:

It reads the workspace first: an id that isn't one of yours exits 1 with 404 workspace_not_found and saves nothing.
It writes workspace_id to the config file, and prints using workspace <workspace_id> (<path>) on stderr, naming the config file. With --json, it also prints the workspace object on stdout.

$NACE_WORKSPACE_ID still wins over the saved workspace, and stderr says so when it's set to another workspace.
nace logout forgets the saved workspace, with the rest of the config file.

Flag	What it does
`--clear`	Forget the saved workspace instead, without a request, and print `cleared the saved workspace` on stderr. Takes no `WORKSPACE_ID`.

List and read workspaces

nace workspaces --name-contains audit
# workspaces (1):
#   <workspace_id>  fy25-audit  active
nace workspace --workspace <workspace_id> --json
nace workspace-stats
# files: 412
# ingestion: failed x8, ingested x398, stale x6
# bytes: 1932735283
# pages ingested: 9120
# index documents: 15004

Command	What it prints
`workspaces`	`workspaces (<total>):`, the number of workspaces that match, then one line per workspace, oldest first, indented two spaces: `<workspace_id> <name> <status>`. When more pages follow, the last line is `next: <cursor>`.
`workspace`	The workspace's line, as `workspaces` prints it. On stderr, which step of Choose a workspace picked it: `from --workspace`, `from $NACE_WORKSPACE_ID` or `from nace workspace-use`. With `--json`, the workspace object.
`workspace-stats`	One fact per line: `files:`, then `ingestion:` with each ingestion status the stats count, sorted, as `<status> x<n>` (left out when there are none), the size in bytes, the pages ingested, and the index documents. With `--json`, every stats field that has a value; one that is `null` is left out.

Command	Flag	What it does
`workspaces`	`--name-contains TEXT`	Only workspaces whose name contains `TEXT`, ignoring case.
	`--limit N`	Workspaces per page, 1 to 200 (default 50). A larger number exits `2`.
	`--cursor CURSOR`	Start at this page: the `next_cursor` of the page before.
	`--all`	Every workspace, across every page. Not with `--cursor`.
	`--json`	Print `{"items": [...], "next_cursor": ..., "total_count": ...}`; `next_cursor` is `null` with `--all`.
`workspace`	`--workspace ID`	The workspace to print. See Choose a workspace.
`workspace-stats`	`--workspace ID`	The workspace to summarize. See Choose a workspace.

Pass a next: line's cursor as --cursor for the next page. An empty list prints workspaces (0):.

Create a workspace

nace workspace-create fy25-audit --domain generic
# <workspace_id>  fy25-audit

nace workspace-create NAME creates a workspace, and prints its <workspace_id> <name> line, or the workspace object with --json.

The name: NAME is 1 to 120 characters, not blank, and can't be changed later; a longer or blank name exits 2 before any request.
A name in use: a name another workspace in the account already has, ignoring case, fails with 409 workspace_name_taken.
Not retried: a retry after a create that went through would fail with that 409. If the command fails with a timeout or a 5xx, check nace workspaces --name-contains before you run it again.

Flag	What it does
`--domain SLUG`	The published domain to sort the workspace's files into, by its slug. Default `generic`. It can't be changed later. See Choose a domain.
`--access JSON`	Access labels for the workspace's files, as a JSON object. They can't be changed later. See Access labels.

What each setting does is in Create a workspace.

Choose a domain

--domain takes the slug of a published domain: generic, one your account published, or one Nace provides. nace domains list --status published lists them; see Domains. A slug that names none exits 1 with 422 invalid_request.

Access labels

--access takes a JSON object: inline JSON, @FILE, a path, or - for stdin. Ingestion gives each file one label, and search then reports what it withheld; see Create a workspace.

Key	What it holds
`labels`	Up to 16 labels, each `{"name": ..., "description": ...}`. Each `name` is lowercase letters and digits joined by `_`. The `description` is what the classifier reads. `[]`, the default, turns labels off.
`default_label`	The label a file gets when the classifier can't decide. Required when there are labels, and must be one of them.

nace workspace-create fy25-audit --access '{"labels": [{"name": "internal", "description": "Staff only."}], "default_label": "internal"}'

Delete a workspace

nace workspace-delete --workspace <workspace_id> --confirm-name fy25-audit
# succeeded workspace_delete <job_id>

nace workspace-delete deletes the workspace and everything in it: every file and version, and what ingestion built. It can't be undone.

How it runs: it starts a workspace_delete job, waits for it as a tool does, and prints the finished job's line on stdout: <status> workspace_delete <job_id>, as the ndi CLI did.
Only --workspace names the workspace: without the flag, it exits 2 before any request, whatever $NACE_WORKSPACE_ID or nace workspace-use say.
The saved workspace: when it was the workspace nace workspace-use saved, the command forgets that too, as soon as deletion is accepted: also with --async, or if waiting for the teardown times out or fails. If the config file can't be written, it warns on stderr and still reports the job.
Who can delete it: the account's owners and admins, or whoever created the workspace. Anyone else gets 403 access_denied.

When it doesn't go as planned:

A job that fails or is cancelled exits 1. Quote its job id when you contact support.
Already gone: if the document service had already let the workspace go, there's no job to wait for: stderr says the workspace was already deleted, and stdout says deleted <workspace_id> at once.
Running it again: the workspace answers 404 workspace_not_found as soon as the delete is accepted, so a second run exits 1 with that error and changes nothing. The command takes no idempotency key.

Flag	What it does
`--workspace ID`	The workspace to delete. Only this flag names it; without it, the command exits `2`.
`--confirm-name NAME`	Required. The workspace's name, exactly. Anything else is refused with `422 invalid_request`.
`--async`	Print only the job id and return at once.
`--wait-timeout SECONDS`	How long to wait for the job (default 600). Past it, the command exits `1` and the deletion goes on: read it later with `nace job <id> --wait`.

Choose a workspaceCopy Anchor Link

List and read workspacesCopy Anchor Link

Create a workspaceCopy Anchor Link

Choose a domainCopy Anchor Link

Access labelsCopy Anchor Link