CLI commands

nt is the command you use to check, inspect, and run your project. This page lists every command and option.

nt <command> [options]

Commands

Options

MCP commands

nt mcp list [SERVER], inspect SERVER TOOL, and doctor [SERVER] connect to trusted servers and accept --json. trust SERVER persists the exact reviewed definition; untrust SERVER removes it. auth SERVER runs the OAuth browser flow and logout SERVER removes that server's stored credentials. See Model Context Protocol guide.

doctor reports ten ordered checks per server: schema, trust, endpoint, connection, authentication, capabilities, catalog, selection, schemas, and shutdown. Failed prerequisites leave dependent checks explicitly skipped. The command exits with status 1 unless every requested server is usable.

Starting a project

nt setup writes a small, working project so you never start from an empty file. Run it in the folder you want to work in:

nt setup

Or name a folder, and NT creates it for you:

nt setup my-agent

$ nt setup my-agent
Setting up an NT project in /Users/you/my-agent
  template: minimal
  + age.nt
  + config.nt

✓ 2 .nt file(s) OK

Next steps
  1. cd my-agent
  2. export ANTHROPIC_API_KEY=sk-ant-...
  3. nt run age -m "bought the first iPhone at 22"

The two starters

nt setup --template full

age.nt                    the entry file: imports + the main agent
config.nt                 settings, defaults, and the provider
sandboxes.nt              the workspace the agent writes in
skills.nt                 a reusable checklist
tools.nt                  a custom shell tool
mcp/local.nt              the selected MCP server and echo tool policy
mcp/echo-server.mjs       a zero-dependency local stdio MCP server
subagents/researcher.nt   a helper agent
workflows.nt              a two-step pipeline

Whatever it writes is checked before it finishes, so a fresh project always passes nt validate. The local server does not need another npm install. Setup also prints these steps before the provider key and first agent run:

nt mcp trust local_demo
nt mcp doctor local_demo

Trust is explicit because a stdio MCP server starts a local process. doctor then connects to the generated server, discovers its echo tool, validates the schemas, and shuts the process down cleanly. The agent asks once per run before calling the tool because its starter policy is approval: once.

Checking your work

validate, list, and graph all work offline, without an AI key. Use them to make sure your project is set up right.

nt validate
nt list
nt graph

Running an agent

run runs something once. Give it input with -i:

nt run age -i '{"clues":"bought the first iPhone at 22"}'

For a quick plain-text message, use -m instead:

nt run age -m "graduated college in 2010"

Add -v to watch what the agent does step by step:

nt run age -m "graduated in 2010" -v

While the model works, up, run, and chat show an animated thinking line:

✻ Pondering… (3s)

It clears the moment the answer arrives, and it is skipped entirely when output is piped or redirected, so scripts and logs stay clean.

Add --show-tool-calls and the line names each step as it happens — every tool call, subagent delegation, and workflow step:

✻ Running tool current_year… (2s)
✻ Delegating to researcher… (4s)
✻ researcher · Running tool fs_list… (5s)

Between steps, while the model itself is thinking, the line returns to the rotating words. Even an instant tool call stays on screen for a moment so it is readable, and while a subagent works the line keeps naming it.

Prefer it always on? Set show_tool_calls: true in your config block and every up, run, and chat behaves as if the flag were passed.

Approving tool calls

A tool declared with confirm: true stops the run and asks before every call with an interactive selector:

⚠ age wants to run current_year({})
❯ Yes, run this tool
  No, deny it (esc)

Arrow keys move, Enter confirms, y/n answer directly, and Esc denies. A denied call is refused; the agent is told and carries on. Pass --yes (or -y) to pre-approve every gated tool for the run. When the terminal cannot ask — output piped or redirected — gated tools are always refused, never silently run. See Ask before running.

Chatting with an agent

chat opens a conversation that remembers what you said earlier. Type exit or press Ctrl-D to leave.

$ nt chat age
Chatting with 'age'. Type 'exit' or press Ctrl-D to quit.
age › she bought the first iPhone at 22
{ "age": 39, "reason": "..." }
age › what if it was the iPhone 15?
{ "age": 31, "reason": "..." }
age › exit

Inspecting the audit log

Every tool call your agents make is appended to a log file. nt audit shows where that file is and what is in it:

nt audit                # the folder, plus the last 20 calls
nt audit --tail 100     # the last 100 calls
nt audit --json         # raw JSONL, for piping into jq

$ nt audit
Audit log
  ● on · config.audit
  folder: /Users/you/.nt/audit

Last 2 tool call(s)
  ● 2026-07-25T10:14:01.204Z age → current_year({}) [custom · 2ms]
  ● 2026-07-25T10:14:02.881Z age → fs_write({"path":"notes.md"}) [builtin · 3ms]

Set audit in your config block to change the folder or turn logging off. See Audit the tool calls.