N
Nanami Docs
Browse docs
Browse docs
Browse docs

Nanami CLI quickstart

Install Nanami CLI, start the local daemon, sign in, connect to a network, and manage exit-node routing.

Section
Browse docs
Path
/ui/client-cli-quickstart

nanami is the client-side tool for sign-in, connection lifecycle, status, and diagnostics. It talks to a local Nanami daemon. Dashboard remains the place for platform setup and policy changes such as networks, routes, DNS, gateways, and access rules.

Use this guide after an operator has already granted your access or after you opened Dashboard -> Nodes -> Add node -> CLI.

What you need

  • Go 1.24.3 if you are building the CLI from source.
  • Reachability to your Nanami control-plane URL.
  • WireGuard tools on the client machine:
    • Linux: sudo apt install wireguard-tools
    • macOS: brew install wireguard-tools
    • Windows: install WireGuard for Windows and make sure wg-quick is available
  • Permission to create and manage local WireGuard interfaces.

1. Build the CLI

Today the documented install path is build-from-source.

Linux and macOS

bash
mkdir -p ./bin
go build -o ./bin/nanami ./apps/client-cli/cmd/nanami
./bin/nanami version

Windows (PowerShell)

powershell
New-Item -ItemType Directory -Force .\bin | Out-Null
go build -o .\bin\nanami.exe .\apps\client-cli\cmd\nanami
.\bin\nanami.exe version

If you want, move the binary into your shell PATH after the build step. The examples below keep using ./bin/nanami; on Windows replace that with .\bin\nanami.exe.

2. Start the local daemon

The CLI stores auth, selected context, selected network, and local runtime state in the local daemon.

Linux and macOS

bash
./bin/nanami service install
./bin/nanami service start
./bin/nanami service status

Nanami installs a user-level service:

  • Linux: systemd --user
  • macOS: launchd user agent

Windows

Windows service installation is not implemented yet. Run the daemon in a dedicated terminal:

powershell
.\bin\nanami.exe daemon run

3. Sign in

Interactive sign-in is the recommended path because it follows the current guided login flow.

bash
./bin/nanami login
./bin/nanami whoami
./bin/nanami context list

What nanami login does:

  • choose Nanami Cloud or Self-hosted,
  • choose endpoint,
  • choose sign-in method,
  • create or update a local daemon-owned context.

Self-hosted currently supports:

  • email and password,
  • the same guided sign-in flow exposed by your deployment.

Nanami Cloud defaults to browser sign-in, and that is also the safer choice when SSO or 2FA is involved.

4. Pick a network and connect

If your account can see more than one network, pick one first:

bash
./bin/nanami network select
./bin/nanami network show

Then connect the device:

bash
./bin/nanami connect
./bin/nanami status

Useful variants:

bash
./bin/nanami connect --network dev
./bin/nanami connect --network dev --node-name macbook-pro
./bin/nanami connect --print-config

nanami connect and nanami up use the same daemon-backed connect flow. Use --print-config when you want to inspect the sanitized WireGuard config without treating client-side config text as the policy source of truth.

5. Check health and logs

bash
./bin/nanami status
./bin/nanami doctor
./bin/nanami watch
./bin/nanami logs

6. Use exit-node routing

bash
./bin/nanami exit-node show
./bin/nanami exit-node set <exit-node-id>
./bin/nanami exit-node off

Current CLI routing model:

  • full-device auto routing,
  • full-device exit-node preference.

Per-application split routing is not implemented yet in the current CLI and backend contract.

7. Disconnect or switch context

bash
./bin/nanami disconnect
./bin/nanami down
./bin/nanami context list
./bin/nanami context use <context-name>
./bin/nanami logout

Non-interactive usage

nanami switches to non-interactive mode when stdin is not a TTY, or when NANAMI_NONINTERACTIVE=1.

Password-based login:

bash
export NANAMI_NONINTERACTIVE=1
export NANAMI_API_BASE_URL=https://api.example.nanami.dev
export NANAMI_CONTEXT=dev
export NANAMI_EMAIL=[email protected]
export NANAMI_PASSWORD='secret'

./bin/nanami login
./bin/nanami connect --network dev --node-name ci-runner --yes
./bin/nanami status --output json

Useful env vars:

  • NANAMI_CONTEXT
  • NANAMI_OUTPUT
  • NANAMI_TIMEOUT
  • NANAMI_WAIT
  • NANAMI_YES

Shell completion

bash
./bin/nanami completion zsh > ~/.zsh/completions/_nanami

Troubleshooting

  • daemon not running: check nanami service status; on Windows keep nanami daemon run running in a separate terminal,
  • 401 unauthorized: run nanami login or nanami auth refresh,
  • 403 forbidden: your account may connect, but platform changes still belong in Dashboard,
  • multiple networks are available: run nanami network select or pass --network,
  • wg-quick missing: install WireGuard tools,
  • MFA challenge in non-interactive mode: use interactive nanami login.

ENFILE / too many open files (dev/CI):

bash
ulimit -n 65536