The nt terminal client: install, TUI, serve and CI
Install the nt terminal client, sign in, run sessions in the TUI, run a server for scripts and other machines, use it in CI, and read the full command and flag reference.
27 min readLast reviewed October 19, 2026Verified against nt 0.0.4 (published 2026-10-19)
What you’ll have at the end
By the end of this guide you will have nt installed, signed in to your Nautili team, and a coding session running in your terminal against your team's gateway. You will also know how nt runs behind the scenes, how to run it as a server that scripts, CI jobs and other machines can drive, and where every flag and environment variable is documented.
Before you begin
- A Nautili account on a team. Sign up at nautili.ai if you do not have one, and ask a team admin to confirm the team has a gateway and at least one connected provider.
- macOS (Apple silicon or Intel) or Linux (x64 or arm64) with
curl, andtar(Linux) orunzip(macOS) on yourPATH; or Windows (x64 or arm64) with PowerShell. Both are covered under Install. - A browser on the same machine for the first sign-in. Headless machines use a token instead, see Step 6.
- A git repository to work in.
ntscopes sessions to the directory you start it from.
Step 1: Install nt
The script detects your OS and CPU, downloads the matching archive from releases.nautili.ai, checks it against the release's SHA256SUMS, and places the binary at ~/.nautili/bin/nt.
It then adds ~/.nautili/bin to your PATH, but only if it is not already there. It picks the config file from $SHELL: for zsh, the first of .zshrc, .zshenv (under $ZDOTDIR or your home) or their $XDG_CONFIG_HOME/zsh copies; for bash, .bashrc, .bash_profile, .profile or their $XDG_CONFIG_HOME/bash copies; for fish, a fish_add_path line in ~/.config/fish/config.fish; for any other shell, .profile, .bashrc or .bash_profile. If none of those files exists, it prints the export PATH=... line for you to add yourself.
The installer accepts these flags after bash -s --:
| Flag | Effect |
|---|---|
-v, --version <version> | Install a specific version instead of the one in the stable manifest, for example --version 0.0.4. A leading v is stripped. VERSION=0.0.4 in the environment does the same when piping. |
-b, --binary <path> | Install from a local binary instead of downloading. |
--no-modify-path | Do not edit any shell config file. You add ~/.nautili/bin to PATH yourself. |
-h, --help | Print the usage text. |
Open a new shell, then confirm the binary is on your path. It prints the version:
Platform notes:
-
Alpine and other musl Linux. The musl build links
libstdc++dynamically and Alpine does not ship it. Runapk add libstdc++before the firstnt. The installer prints this reminder when it picks a-musltarget. -
Windows. There is a PowerShell installer. In Windows PowerShell 5.1 or PowerShell 7, run:
It reads the same release manifest, downloads
nt-windows-x64.zip(or-arm64, or-x64-baselineon a CPU without AVX2), checks it againstSHA256SUMS, putsnt.exein~\.nautili\bin, and adds that directory to your userPATH. Run the script from a file to pass flags:-Version <v>,-InstallDir <path>,-NoModifyPath. When piping,$env:VERSION = "0.0.4"pins the version. -
GitHub Actions. When
GITHUB_ACTIONS=true, both installers also append the install directory to$GITHUB_PATH, so later steps in the job findntwithout aPATHedit.
To move to the current release later, run the upgrade command (nt update is an alias):
nt upgrade acts only on a copy it recognises: the installer's binary in ~/.nautili/bin, or an @nautili/tui install made with npm, pnpm, bun or yarn. For the installer's copy it re-runs the installer with the target version; on Windows that is the PowerShell installer. For any other nt it refuses with Nautili at <path> is not managed by its installer. Pass --method curl to install the current version with the installer, or run: curl -fsSL https://nautili.ai/install.sh | bash. nt upgrade 0.0.4 pins a version, and an explicit target may also downgrade; without a target, nt upgrade never moves below the published release.
Step 2: Sign in
nt login starts a browser OAuth flow. It prints Authorize Nautili in your browser and choose a team. and the authorization URL, opens the URL in your browser when run from a terminal, and waits for you to approve and pick a team. On approval it prints Logged in as <email> (<team>).
The credential is stored in ~/.local/share/nautili/nautili.db ($XDG_DATA_HOME is respected), encrypted with a key held in the OS keychain: macOS Keychain, Secret Service on Linux, or DPAPI on Windows. On a headless host with no keychain, the key falls back to a credential.key file (mode 0600) beside the database, and nt prints a one-time notice saying so. DEVZERO_CREDENTIAL_STORE=keyring or =file forces one or the other.
The same login covers the TUI, nt run, nt serve and the desktop app on this machine, because they all share the background service described in How nt runs. nt login takes only --standalone or --server <url> to sign in a different server.
Check what the install thinks it is:
The gateway line matters. When the gateway is ready it names the gateway and the URL the client will send traffic to; any other state is spelled out instead, with a remedy line under it saying what to do, and the TUI shows the gateway state in its status line. The access token refreshes on its own before it expires.
nt whoami --json prints the same state as data, with no token in it, and it succeeds even when nothing is logged in. The fields are trimmed here to the ones you will look at:
nt logout revokes the grant on the DevZero side and removes the local row, printing Logged out of DevZero. If the revoke call fails, it still signs out locally and tells you to withdraw the session from the dashboard. If DEVZERO_TOKEN is set where the server runs, it adds Still signed in with DEVZERO_TOKEN: unset it where the server runs to sign out.
Step 3: Set your defaults
nt reads a config file named nautili.jsonc, nautili.json, opencode.jsonc or opencode.json. The global copy lives in ~/.config/nautili/. A project can carry its own at the repo root, or inside a .nautili/ directory (.opencode/ is read too), and it merges on top of the global file. The keys most people set:
Each key is optional. nt models prints the ids your gateway serves, in the form devzero/<author>/<slug>; the part after devzero/ is the same model id the gateway accepts over HTTP.
Server settings are not config keys. The background service's address is set with nt service set port 4096 and nt service set hostname 0.0.0.0, see How nt runs.
TUI keybindings live under a keybinds object in the same config file. Names are dotted; the defaults are listed in Step 4 and you only add the entries you change. A tui.json from an older version is migrated into the config file on first run.
Step 4: Work in the TUI
Start nt from inside a repository:
The TUI opens on a new session scoped to that directory, with the model from your config selected. Type a prompt and press return to send it; shift+return inserts a newline. While the agent is working, escape interrupts it. A permission prompt appears before nt edits a file or runs a command it has not been allowed to; answer it in place.
Starting options worth knowing:
| Command | What it does |
|---|---|
nt ~/src/other-repo | Start in a different directory without cd. |
nt -c | Continue the most recent session in this directory. |
nt -s <session-id> | Reopen a session, or create one with that id. |
nt --prompt "explain the build" | Start with a prompt already submitted. |
nt --auto | Auto-approve every permission that is not explicitly denied. Use with care. |
nt --standalone | Run against a private server for this one process instead of the background service. |
nt --server http://host:port | Attach to a server you started elsewhere; set NT_PASSWORD for its password. |
nt mini | The minimal interface. Takes -c, -s, --fork, -m <provider/model>, --agent, --prompt, and --no-replay or --replay-limit <n> to control history replay. |
The key bindings below are the defaults. The leader key is ctrl+x: press it, release, then press the second key.
| Keys | Action |
|---|---|
ctrl+p | Command palette. Everything below is reachable from here by name. |
ctrl+x n | New session |
ctrl+x l | List sessions |
ctrl+o | Open recent sessions and projects |
ctrl+x m | List models and switch the current session to one |
f2 / shift+f2 | Cycle recently used models forward or back |
ctrl+t | Cycle the model variant (provider-specific reasoning effort) |
ctrl+x a, shift+tab | List agents, or cycle to the next agent |
ctrl+x c | Compact the session to reclaim context |
ctrl+x e | Open the external editor for the prompt |
ctrl+x y / u / r | Copy, undo or redo the last message |
ctrl+x b | Toggle the sidebar |
ctrl+x t | Toggle the terminal pane |
ctrl+x s | Status view, including the gateway state |
ctrl+r | Rename the session |
escape | Interrupt the running turn |
ctrl+c, ctrl+d, ctrl+x q | Exit |
Switching models mid-session is the common case for cost control: open ctrl+x m, pick a cheaper model for the next turn, and the session keeps its history. The dashboard records which model served each request, so a session that moved between models shows both.
For one-shot work without the interface, nt run sends a message and prints the reply:
nt run reads a message from its arguments, from stdin when piped, or both. It uses the same session store as the TUI, so nt run -c "now fix the first one" continues the last session, and nt -c later opens it in the TUI. --format json emits raw events for scripting, -f <path> attaches files, and --title names the session.
How nt runs
Every nt command talks to a background service: one server process per machine, listening on port 49380 (45284 on Windows), started on demand the first time a command needs it and kept running afterwards. The TUI, nt run, nt models and the desktop app all connect to it, which is why a login in one covers them all. nt service start|status|stop|restart manages it, and nt service set hostname|port|password|cors <value> changes its settings, stored in ~/.config/nautili/service.json; the running service's address is registered under ~/.local/state/nautili/service.json. Any setting change stops the service so the next command restarts it with the new value.
Two flags step around the service. --standalone starts a private server for that one command and stops it afterwards. --server <url> targets any server, local or remote, with the password from NT_PASSWORD.
Step 5: Run a server for scripts and other machines
nt serve runs the same server in the foreground, on an address you choose:
Without a password in the environment the server generates one and prints it, with a link that signs a browser in. Pass --port so the address is predictable. The hostname defaults to 127.0.0.1; pass --hostname 0.0.0.0 to accept connections from other machines, and set the password yourself when you do:
The server uses HTTP basic auth with the fixed username opencode and that password. NT_PASSWORD is the variable to set; the older NT_SERVER_PASSWORD is still honoured. There is no unsecured mode. --cors <origin> (repeatable) adds allowed browser origins.
Check it is up. /api/info needs no login and returns the server's info JSON:
The login gate applies to the server too. Until it has a credential from nt login (or a DEVZERO_TOKEN in its environment), only /api/info, /openapi.json, the DevZero integration and OAuth routes, the OAuth callback, and the status and logout RPCs answer; everything else returns 401 with Log in to DevZero to use Nautili. Sign in before you start the server, or supply a token as in Step 6.
Drive it from a script. The server publishes its API as /openapi.json, and nt api calls any operation in it by operationId, or by METHOD /path:
Every request that touches a project names it with the x-opencode-directory header (an absolute path on the server); without it the server uses its own working directory. --param fills path parameters and adds the rest as query parameters; -d sends a JSON body. On a non-2xx response nt api prints HTTP <status> to stderr and exits 1.
To work interactively against a server on another machine, point a client at it:
-c and -s <id> work the same as for a local nt, and nt run --server http://<host>:4096 "..." does the one-shot equivalent. The desktop app can add the same server under Settings, Servers.
Step 6: Run nt in CI
A runner has no browser, so it signs in with a token. When DEVZERO_TOKEN is set, nt starts a private server for the command (the same thing --standalone does; pass it anyway so the intent is visible), and that server exchanges the token for a short-lived access token when it starts. nt whoami --json then reports the real gateway.state, and nt models lists the catalogue. If the account belongs to several teams, also set DEVZERO_TEAM=<team id> so the exchange knows which one to act for. Store the token as a repository secret, never in the workflow file.
The installer appends ~/.nautili/bin to $GITHUB_PATH, so the later steps find nt. nt run refuses with Not logged in to DevZero. Run `nt login`. and exit code 1 when stdout is not a TTY and no identity is present, which is the failure you want on a misconfigured secret. nt models exits non-zero with the backend's reason when the token was refused, so an empty catalogue never reads as success.
With a token, nt whoami prints <email> (<team>) and then Signed in with DEVZERO_TOKEN (personal access token exchange). If the machine also has a stored login, the stored login wins and nt whoami says so: DEVZERO_TOKEN is set but unused: the stored login wins. Run `nt logout` to use it. The long-lived background service never inherits a token from the shell that started it; nt service set env DEVZERO_TOKEN <value> is the way to give it one.
Verify
Everything nt sends goes through the same gateway as your SDK traffic, so the dashboard is where you confirm it worked.
- Send one prompt from the TUI or
nt run. - Open Spend. Group by user and the row for your account moves. Group by workload type and the request sits under
nautili: the client stampsX-Dz-Workload-Type: nautilion every request, and aUser-Agentofnautili/prod/0.0.4/cli. Each request also carriesX-Dz-Session-Id,X-Dz-Labels: agent=<agent>and a W3Ctraceparentderived from the root session, so a resumed session rejoins its trace. The gateway strips anyX-Dz-UserorX-Dz-Teama client sends, because the token already carries both, verified. - Open Traces and find the request. The decision record shows the requested, decided and served model. In
shadowmode a guardrail's would-deny is recorded on the trace while the request is still served; inenforcemode the deny surfaces in the TUI as a provider error.
Locally, nt whoami is the health check. DEVZERO_TRACE=1 nt whoami --standalone --print-logs logs each call the server makes to the control plane (method, path, status, duration, whether a bearer was attached, and no token or body); the trace has to run on a server you start, which is what --standalone does.
Options
Only flags present in the current build are listed. Hidden development-only flags are omitted.
nt
Starts the TUI. directory is a path to start in; relative paths resolve from your shell's working directory.
| Flag | Type | Default | Description |
|---|---|---|---|
-c, --continue | Typeboolean | Default | DescriptionContinue the last session in this directory |
-s, --session <id> | Typestring | Default | DescriptionSession id to continue, or to create if it does not exist |
--prompt <text> | Typestring | Default | DescriptionPrompt to submit on start |
--auto | Typeboolean | Defaultfalse | DescriptionAuto-approve permissions that are not explicitly denied |
--standalone | Typeboolean | Defaultfalse | DescriptionRun with a private server instead of the background service |
--server <url> | Typestring | Default | DescriptionConnect to a server URL instead of the background service |
Other commands: upgrade (alias update), uninstall (--dry-run, -f/--force), acp, api, debug agents|config|paths, auth list|login|logout|export|import|switch, login, logout, whoami, mcp list|add|auth|logout, plugin list|add|check|update|remove, models, stats, mini, run, session list|delete|export|import, service start|restart|status|stop|get|set|unset, reload, pair, serve. nt <command> --help lists each one's flags.
nt mini
The minimal interactive interface. Takes -c, -s <id>, --fork, -m <provider/model>, --agent <name>, --prompt <text>, --replay / --no-replay and --replay-limit <n> (default 200), plus --standalone and --server <url>.
nt run
Sends one message and prints the reply. Message text comes from the arguments, from piped stdin, or both. Needs an identity: it prompts for login on a TTY and exits 1 otherwise.
| Flag | Type | Default | Description |
|---|---|---|---|
-c, --continue | Typeboolean | Default | DescriptionContinue the last session |
-s, --session <id> | Typestring | Default | DescriptionSession id to continue, or to create if it does not exist |
--fork | Typeboolean | Default | DescriptionFork before continuing (requires -c or -s) |
-m, --model <provider/model#variant> | Typestring | Defaultconfig model | DescriptionModel to use, for example -m devzero/anthropic/claude-haiku-4.5#high |
--agent <name> | Typestring | Default | DescriptionAgent to use |
--format <default|json> | Typestring | Defaultdefault | DescriptionFormatted output, or raw JSON events |
-f, --file <path> | Typestring[] | Default | DescriptionFile(s) to attach to the message; repeatable |
--title <text> | Typestring | Default | DescriptionSession title |
--thinking | Typeboolean | Defaultfalse | DescriptionShow thinking blocks |
--auto | Typeboolean | Defaultfalse | DescriptionAuto-approve permissions that are not explicitly denied |
--standalone | Typeboolean | Defaultfalse | DescriptionRun with a private server instead of the background service |
--server <url> | Typestring | Default | DescriptionSend to a server URL instead of the background service |
nt serve
Starts the server in the foreground.
| Flag | Type | Default | Description |
|---|---|---|---|
--port <n> | Typenumber | Default | DescriptionPort to listen on |
--hostname <host> | Typestring | Default127.0.0.1 | DescriptionInterface to bind |
--cors <origin> | Typestring[] | Default | DescriptionAdditional allowed CORS origin; repeat for several |
--service | Typeboolean | Defaultfalse | DescriptionRun as the background service (what nt service start launches) |
--stdio | Typeboolean | Defaultfalse | DescriptionReport the address as JSON on stdout and exit when stdin closes (what --standalone launches) |
nt service
Manages the background service. Keys: hostname, port, password, cors (comma-separated origins), disabled (true stops the service and makes every command run standalone), and env (nt service set env <NAME> <value>, for variables the service should run with).
nt api
Makes one request to the server and prints the response body.
| Flag | Type | Description |
|---|---|---|
Flag-d, --data <body> | Typestring | DescriptionRequest body; content-type: application/json is set unless you pass one |
Flag-H, --header <name:value> | Typestring[] | DescriptionRequest header; repeatable |
Flag--param <key=value> | Typestring | DescriptionOpenAPI path or query parameter |
Flag--standalone, --server <url> | Type | DescriptionAs for nt |
nt models
Lists the models your team's gateway serves, one providerID/id per line, sorted, for example devzero/anthropic/claude-haiku-4.5. Needs an identity. Exits non-zero with the backend's reason when a DEVZERO_TOKEN is refused.
nt login
Opens the browser OAuth flow and stores the credential on the server it talks to.
nt logout
Revokes the grant server-side, then removes the local credential, the cached gateway choice and the team instructions.
nt whoami
Prints the signed-in account, team, gateway state, backend and token expiry.
| Flag | Type | Default | Description |
|---|---|---|---|
--json | Typeboolean | Defaultfalse | DescriptionDump the runtime state as JSON (never includes a token); succeeds when logged out |
nt upgrade
Installs the current release, or target (0.0.4 or v0.0.4). Skips when the target is already installed. Without a target it never moves below the published release; an explicit target can.
| Flag | Type | Description |
|---|---|---|
| Flag-m, --method <name> | Typestring | DescriptionInstallation method: curl (the installer; the PowerShell installer on Windows), npm, pnpm, bun, yarn, vp, brew, winget. Detected when omitted; only curl and the npm-family methods apply to Nautili. |
Global flags
These apply before any command.
| Flag | Description |
|---|---|
-h, --help | Show help for nt or a subcommand |
--version | Print the version |
--print-logs | Print logs to stderr; server logs require --standalone |
--trace [filter] | Log every outbound HTTP call and every request served; --trace=<filter> narrows it to origins and paths containing one of the comma-separated filters, for example --trace=api.nautili |
Environment variables
| Variable | Effect |
|---|---|
DEVZERO_TOKEN | Personal access token. The server exchanges it for a short-lived access token at start, for headless and scripted use. A command run with it set uses a private server. |
DEVZERO_TEAM | Team id a DEVZERO_TOKEN acts for, needed when the token's account is in more than one team. |
DEVZERO_CREDENTIAL_STORE | keyring or file: force where the credential key is kept. Default: the OS keychain, falling back to a file. |
DEVZERO_TRACE | 1 logs every call to the Nautili control plane, one line each: method, path, status, duration, whether a bearer was attached. No token or body is ever logged. 0, false or off disable it. |
NT_TRACE | What --trace sets. 1 traces all hosts; any other value is a comma-separated filter. |
NT_PASSWORD | Basic auth password: adopted by nt serve, and sent by clients using --server. NT_SERVER_PASSWORD is the legacy name and still works. |
NT_CONFIG | Path to a config file to load instead of the discovered ones. |
NT_CONFIG_DIR | Override the config directory. |
NT_DISABLE_AUTOUPDATE | 1 stops the client from checking for and installing releases on its own. |
NT_PRINT_LOGS, NT_LOG_LEVEL | NT_PRINT_LOGS=1 is what --print-logs sets; NT_LOG_LEVEL sets the level of those logs. |
NAUTILI_RELEASES_URL | Installer only: base URL for the release manifest and archives, default https://releases.nautili.ai. |
NAUTILI_BINARY | Installer only: the binary name to install, default nt. |
NAUTILI_INSTALL_DIR | Installer only: where to put the binary, default ~/.nautili/bin. |
Every NT_* variable is copied to its OPENCODE_* name at startup, so either spelling works.
Troubleshooting
| Symptom or error | Cause and fix |
|---|---|
nt: command not found after install | The shell config was edited but not reloaded, or --no-modify-path was used. Run export PATH=$HOME/.nautili/bin:$PATH or open a new shell. |
Unsupported OS: MINGW64_NT... from the installer | The bash installer does not run on Windows. Use the PowerShell installer: irm https://releases.nautili.ai/install.ps1 | iex. |
Checksum mismatch for nt-linux-x64.tar.gz ... Nothing was installed. | The download did not match SHA256SUMS. Retry; if it persists, a proxy is altering the download. |
Error loading shared library libstdc++.so.6 on Alpine | The musl build needs libstdc++. Run apk add libstdc++. |
Not logged in to DevZero. Run `nt login`. | A gated command (the TUI with -s, run, mini, models, stats, acp, reload, session *, mcp *, plugin *, debug agents, debug config) ran without an identity on a non-TTY. Sign in, or set DEVZERO_TOKEN. |
Log in to DevZero to use Nautili (HTTP 401) from a server | The server has no credential. Run nt login against it (--server <url> for a remote one), or start it with DEVZERO_TOKEN set. |
DEVZERO_TOKEN is set but unused: the stored login wins. | Both identities are present. nt logout removes the stored login if the token is the one you want. |
The gateway line in nt whoami is not ready | nt whoami prints the state and the remedy; the TUI shows the same in its status line. Usually the team has no gateway resolved yet; ask a team admin. |
Server at <url> requires a password; set NT_PASSWORD | --server was used without a password. Export NT_PASSWORD with the server's password. |
Server at <url> rejected the password | Wrong NT_PASSWORD for that server. |
Could not reach server at <url> | Nothing is listening there, or a firewall is in the way. Check nt serve is running on that host and port. |
Warning: Server at <url> has version X; this client is Y. Continuing anyway. | Client and server differ. Upgrade both to the same release. |
401 from curl against nt serve | Basic auth is on. Use -u opencode:<password>. |
Managed service port 49380 on 127.0.0.1 is already in use by another process. | Something else holds the service port. nt service set port <port>, then run the command again. |
--fork requires --continue or --session | --fork only applies when resuming. Add -c or -s <id>. |
You must provide a message | nt run got empty input. Pass a message argument or pipe stdin. |
Nautili at <path> is not managed by its installer. | nt is not at ~/.nautili/bin/nt and not an npm-family install. Run the install command it prints, or nt upgrade --method curl. |
Next steps
- Install Nautili for the desktop app and release checksums, if you want the same sessions in a window.
- Keys and credentials to issue a service key for scripts that call the gateway directly instead of through
nt. - Guardrails overview to put a budget and a model allowlist on the identity your CI runs as.
- Spend attribution to see how
nautilitraffic rolls up by user, team and workload type. - Gateway headers for the
X-Dz-*request and response headers you will see on every trace. - The Nautili desktop app for the same sessions in a window, sharing this machine's background service and
nt login. - Keys: scopes, rotation and custody for the service key a CI job or script should hold.
- Govern LLM traffic with guardrails to put a budget and model allowlist on what
ntcan spend.