Get started
CLI
Install the nace command, sign in, ask Drex's decision model calibrated questions, and run Perception's document tools, uploads, jobs, saved schemas, workspaces, storage connections and search from the shell.
nace-cli installs the nace command, which calls https://console.nace.ai from your shell. It is built on the Python SDK. It asks Drex's decision model calibrated questions with nace decide and runs Perception's five tools, uploads, jobs, job files, saved extraction schemas, workspaces, storage connections, ingestion and search. This page covers installing, signing in and the flags every command takes. The sections in the sidebar cover each group of commands, and Every command lists them all.
Install
pipx install nace-cli # or: uv tool install nace-cli
nace login
nace parse https://example.com/report.pdf > report.mdnace-cli needs Python 3.11 or later. It checks TLS certificates against your operating system's certificate store, so a proxy certificate your system trusts works too.
These examples target 0.5.0. Run nace version and nace --help to check the versions and commands you have installed; an older package can have different commands. Upgrade the CLI and SDK together when the target version is available from the package index.
nace version and nace --version print the CLI and SDK versions:
nace 0.5.0
nace-sdk 0.7.0Sign in
nace login # type the key; it isn't echoed
nace login --api-key - < key.txt # or read it from stdin, for scripts| Flag | What it does |
|---|---|
--api-key [KEY] | The nace_sk_ key. - reads the first line of stdin, or asks at a hidden prompt at a terminal. Omit KEY, or the whole flag, to type the key at a hidden prompt. |
--base-url URL | Validate and save a custom or on-prem API root with the key. |
nace login then:
- Checks that the key looks like a Nace API key:
nace_sk_followed by 43 characters. Anything else exits2before any request. - Checks it against Drex with
GET /v1/models, which is free at any balance. It asks--base-url, else$NACE_BASE_URL, else the base URL saved earlier, elsehttps://console.nace.ai. A refused key exits1. - Saves it to
~/.nace/config.toml, readable only by you, and printssaved API key to <path>on stderr.
The actual URL used for validation is saved with the key, including when selected through $NACE_BASE_URL or the default. Without --api-key and without a terminal, as in CI, nace login exits 2, and so does --api-key with no KEY: pass --api-key KEY or --api-key -.
nace logout deletes the config file, a saved base URL and workspace included, and the legacy ~/.drex/config.toml when no path variable is set, and prints removed <path> (or no saved API key) on stderr.
Credentials and settings
| Variable | What it does |
|---|---|
NACE_API_KEY | The API key. Wins over api_key in the config file. |
NACE_BASE_URL | The API host. Wins over base_url in the config file; without either, https://console.nace.ai. Use the key for that deployment; see below. |
NACE_CONFIG_PATH | Where the config file is, instead of ~/.nace/config.toml. nace login and nace logout use it too. |
NACE_DEFAULT_DECISION_MODEL | The model nace decide asks when neither -m nor --body names one. Default drex-latest. |
NACE_LOG_LEVEL | Log each request to stderr. See Logging. |
NACE_WORKSPACE_ID | The workspace a workspace command uses when you don't pass --workspace. Wins over workspace_id in the config file. See Choose a workspace. |
The names from before the packages were renamed from drex-* still work when the new ones are unset or blank: DREX_API_KEY, DREX_BASE_URL, DREX_CONFIG_PATH, DREX_DEFAULT_MODEL and DREX_LOG_LEVEL. So does the file drex login wrote, ~/.drex/config.toml, which is read when ~/.nace/config.toml doesn't exist and no path variable is set. nace login always writes ~/.nace/config.toml, and nace logout deletes both files. |
NACE_API_KEY and NACE_BASE_URL work together for cloud, custom and on-prem deployments. Environment values override the corresponding saved values; setting both requires no login or profile. The legacy DREX_* names remain supported. Treat the API root as trusted configuration and select its matching key. URLs with user information are refused.
For an on-prem server, validate and save its key and URL together:
nace login --base-url https://nace.customer.example --api-key - < key.txtThe profile works for both the CLI and MCP, but is optional: the environment pair works directly. For unattended profile use, mount the mode-0600 file and set NACE_CONFIG_PATH to it. Environment values still take precedence over the saved configuration.
The config file holds at most three keys:
api_key = "nace_sk_..."
base_url = "https://console.nace.ai" # actual root validated at login
workspace_id = "0f8b7c2e-..." # only after nace workspace-useWith no key in either place, a command exits 2 with error: no API key and says to set $NACE_API_KEY or run nace login. An unreadable config file exits 2 too, unless $NACE_API_KEY is set.
Flags every API command takes
Every command except login, logout, skill drex-search, skill drex-workspace, skill install and version takes --json and --timeout, and every command, nace itself included, takes -h, --help. Put them after the command name: nace models --json, not nace --json models.
| Flag | What it does |
|---|---|
--json | Print JSON instead of text. What each command prints is in its section. |
--timeout SECONDS | How long each HTTP request may take (default 120). A document create with --wait-seconds N gets N seconds more. For file downloads and event streams it bounds only connecting, not how long the data takes to arrive. |
-h, --help | Print the command's flags and exit. |
Text and JSON values
A flag's value can be text, JSON, or the contents of a file or of standard input. There are three ways to give it:
- Inline: type the value. Text is used as it is, and JSON is parsed:
--schema '{"type": "object", "properties": {"total": {"type": "number"}}}'. - From a file: put
@before the path:--state @ticket.txt. A flag that takes JSON also accepts a bare path to a file that exists. - From stdin: pass
-:cat ticket.txt | nace decide --state - ....
Not every text flag reads files. --name and --instructions, for example, take what you type, so --instructions @notes.txt sends the text @notes.txt.
Only one flag per command can read stdin. A command that gives - to two flags, such as --state - --questions -, exits 2 before it sends any request.
Text piped in with - is read as UTF-8, and a byte-order mark at its start is dropped; stdout and stderr are UTF-8 too, on every platform. Windows PowerShell 5.1 replaces non-ASCII characters with ? before they reach any program it pipes to, so pass such text with @FILE there.