CLI reference

nordai — the agent in your terminal

A Node.js and TypeScript CLI with streaming output, a real tool loop, approvals, session persistence and a workspace boundary. It never holds the router key.

Install API reference

Install and sign in

npm install -g nordai@latest

Requires Node.js 20.11 or newer. Then run nordai in your repository and use /login, or authenticate before starting:

nordai login

Device login prints an 8-character code and a verification URL. Approve it at Dashboard → Devices. The CLI polls the API until approval, then stores a 30-day revocable device credential. You can revoke it from the dashboard at any time.

API-key login

For CI or scripted use, create a key in the dashboard and export it as NORDAI_API_KEY. Keys are shown once and stored only as a hash. Use per-key model, rate and monthly limits to constrain automation.

Commands and flags

nordai                              # interactive workbench
nordai "Analyze this repository"    # one autonomous task, then exit
nordai --cwd ./my-project           # workspace root
nordai --model <available-model-id> # model for this session
nordai --approval auto-edit         # manual | auto-edit | read-only
nordai --version
nordai doctor
nordai login
nordai sessions
nordai resume <session-id>

Model ids must come from GET /api/v1/me/models or /model. Unknown ids are rejected by the gateway rather than silently substituted.

Interactive commands

Command	Behaviour
/help	List commands and current mode
/login	Device authorization flow (or set an API key)
/logout	Revoke the local credential and server device token
/model	List allowed models and switch the active one
/providers	Show the provider behind each allowed model
/plan	Plan, expiry and remaining allowance
/approval	Switch between manual, auto-edit and read-only
/init	Create a NORD.md project brief for the agent
/files	List files tracked in the current context
/diff	Show the working diff produced by this session
/review	Ask the model to review the current diff
/undo	Restore files changed by the last approved step
/new	Start a fresh session
/resume	Resume a stored session
/compact	Summarise older turns to free context
/usage	Requests and tokens used against your plan
/settings	Endpoint, model, approval mode, context budget
/doctor	Diagnose Node, API, credentials and workspace
/exit	Exit the workbench

Tools and approvals

The model can only act through these tools. Mutating tools require approval in the default mode; read-only tools do not.

Tool	Class	Notes
read_file	read	Reads a file inside the workspace (secret files excluded)
write_file	write	Creates or replaces a file; requires approval unless auto-edit
edit_file	write	Applies an exact string replacement and records undo state
list_files	read	Walks directories, skipping ignored and secret paths
search_files	read	Regex search with result caps and binary skipping
run_command	exec	Runs a shell command through the allow/deny policy with a timeout
git_status	read	Shows the working tree status
git_diff	read	Shows the diff for tracked files
ask_user	prompt	Pauses the loop to ask a clarifying question
finish_task	final	Ends the loop and produces the summary

Approval modes

manual (default): every write and command asks for confirmation.
auto-edit: file writes apply automatically; commands still ask.
read-only: writes and commands are refused; the agent can still analyse and explain.

Security model

Workspace root is fixed at startup; every path is resolved and checked against it.
Symlinks that escape the workspace are rejected; secret files are excluded from reads and search.
A deny-list blocks destructive commands and an allow-list constrains execution.
Commands have a timeout and output cap; the agent has a maximum step count and loop detection.
Ctrl+C cancels the current task and records the session as cancelled.
Credentials are never placed in a URL, a command line or a log line.

Sessions and files

Configuration, credentials and local session state live in ~/.nordai (%USERPROFILE%\.nordai on Windows). On POSIX systems the directory is created with 0700 and credential files with 0600. Sessions are also mirrored to your NordAI account when you are signed in, enabling /resume on another machine.

/compact asks the model to summarise older turns, then replaces them in the context while keeping the system prompt and recent tool results. The summary is stored in the session.

Troubleshooting

nordai doctor reports Node, API reachability, credential validity and workspace state.
quota_exceeded responses include a reset time; the CLI prints it and stops retrying.
401 after a long break usually means the device credential was revoked or expired — run /login again.
If a command is blocked, check the deny rules in /settings before assuming a bug.