CLI Reference

CLI Reference

navette --version          # print version, exit
navette --help             # usage

Subcommands

Subcommand	What it does
serve	HTTP JSON API on 127.0.0.1 (default port 8765). The only mode that opens listeners.
mcp	MCP stdio server for agent hosts (19 tools). Auto-starts serve if nothing is listening; idles politely if the port is already served by another navette.
state	Manage logged-in states (cookie jars) in the OS keychain — see below.
creds	Manage origin-bound login credentials in the OS keychain — see below.
install-daemon	Install the resident daemon (LaunchAgent on macOS with KeepAlive, systemd user unit on Linux, schtasks on Windows — all run navette serve --port 8765).
uninstall-daemon	Remove it (systemctl --user daemon-reload included on Linux).

serve flags

Flag	Effect
--port N	Listen port (default 8765). Loopback only — there is no flag or env that binds a non-local interface.
--token SECRET	Require Authorization: Bearer SECRET (or X-Navette-Token) on every route except /health. Comparison is constant-time. An MCP host attaches with the NAVETTE_TOKEN env var.
--proxy URL	HTTP CONNECT / SOCKS5 proxy for the wry backends (Windows/Linux); on macOS the system proxy is followed. Proxy URLs are credential-redacted (scheme://***@host) in logs.
--user-agent UA	Per-serve User-Agent override for every session.
--idle-release MIN	Drop idle WebKit sessions after MIN minutes without requests. The daemon stays resident; the next request re-warms through the pre-warm path (~100 ms). Validated on macOS and Linux.
--allow-host NAME	Repeatable. Extra Host headers the DNS-rebinding guard accepts — for container/tunnel access (e.g. navette serve --allow-host host.docker.internal). Pair with --token once anything beyond loopback can reach it; the daemon warns and the docs require the pairing.

state — logged-in states (cookie jars)

The daemon owns the keychain. Only metadata (names, origins, timestamps) ever travels — the jar never crosses the wire.

navette state save NAME  [--session S] [--url U]   store the session's logged-in state in the OS keychain
navette state load NAME  [--session S] [--url U]   restore it into the session
navette state list       [--url U]                 stored states (names + origins, never the jars)
navette state delete NAME [--url U]                remove one

--url defaults to $NAVETTE or http://127.0.0.1:8765. macOS re-prompts for keychain access when the binary changes (ACL) — an implicit per-release consent.

Equivalent HTTP: POST /sessions/state {"session":S,"store":NAME} and POST /sessions/load {"session":S,"store":NAME} — see HTTP API Reference.

creds — origin-bound credentials (the human step)

navette creds set NAME [--session S] [--url U]     save a login (HUMAN step: prompts on hidden stdin;
                                                   binds to the origin of the session's current page)
navette creds list [--url U]                       sites + origins + usernames — never passwords
navette creds delete NAME [--url U]                remove one

creds set binds the credential to the exact origin of the session's current page — navigate that session to the site's login page first. The agent then logs in with POST /login {"site": NAME}: the password is resolved inside the daemon and injected into the page; it never appears in the request, the response, or a log, and there is no read-back API at all. Details: Secrets and Logins.

Environment variables

Variable	Read by	Effect
NAVETTE_TOKEN	MCP mode, state/creds CLI	The bearer token attached to daemon calls.
NAVETTE_EVAL_TIMEOUT_SECS	serve	/evaluate timeout. Default 20, clamped 5–300. The mitigation for slow/contended environments (issue #7's sibling).
NAVETTE_SIZE	wry backends	Default ghost-window size at process start, WxH (e.g. 1920x1080). Bad values are ignored with a warning.
NAVETTE	state/creds CLI	Base URL of the daemon (default http://127.0.0.1:8765).
PORT	container image	serve port inside the container (image default 8765).

Ports on a shared machine

Multiple daemons can coexist on one machine (each chat plugin / agent setup keeps its own list of known ports and probes them in order). The only rule: never assume a port serves navette — probe GET /health and require {"name":"navette","ok":true}. Anything else (a Python dev server, another app) answers differently or in HTML.