np-agent CLI

np-agent is the host agent: it collects basic system metrics, runs local Nagios plugins on a schedule and pushes everything as passive results over HTTPS to POST /api/v1/results — no inbound ports on the monitored host. Optionally it pulls centrally defined checks from the server and/or listens NCPA-style so the server can poll it. This page is the command-line and configuration reference; the operational deep dive (collectors, protocol, install snippets, troubleshooting) is Agent.

Flags

np-agent -config /etc/northplane/agent.yaml
np-agent -version          # prints: np-agent <version>

Flag	Default	Meaning
-config <path>	see below	path of agent.yaml
-version	—	print np-agent <version> and exit 0

Go flag semantics: -flag and --flag are equivalent. There is no further usage text — an unknown flag prints Go’s Usage of np-agent: with these two flags and exits 2. The agent reads no other command-line input; everything else comes from agent.yaml and one environment variable.

Config file location

The default path mirrors the server’s rule:

1. /etc/northplane/agent.yaml when running as root, or when that file exists;
2. otherwise <user config dir>/northplane/agent.yaml — Linux $XDG_CONFIG_HOME/northplane/agent.yaml (default ~/.config/northplane/agent.yaml), macOS ~/Library/Application Support/northplane/agent.yaml, Windows %AppData%\northplane\agent.yaml;
3. fallback /etc/northplane/agent.yaml.

The service snippets generated by Admin → Agents pass -config /etc/northplane/agent.yaml (Linux/macOS) or -config C:\ProgramData\northplane\agent.yaml (Windows) explicitly.

Environment

Variable	Effect
NORTHPLANE_TOKEN	overrides token from the file when non-empty — keeps the secret out of the YAML

No other environment variables are read; plugins started by the agent get an environment of only PATH=<plugin search path> and LC_ALL=C (nothing inherited).

agent.yaml reference

YAML, decoded strictly by type (no unknown-key check). Durations are strings with a unit: interval: 60s is valid, interval: 60 is a parse error.

Key	Type	Default	Meaning
server	string	required	base URL of the Northplane instance, e.g. https://northplane.example.net (trailing / trimmed)
token	string	required unless NORTHPLANE_TOKEN is set	API token np_… with scope objects:write (plus objects:read when pull: true)
hostname	string	OS hostname	the host name sent with every result and used for the pull query — must equal the Host object’s name on the server
insecure	bool	false	skip TLS verification for push and pull
interval	duration	60s	collection + push tick; also the cadence for pulled checks without their own interval
disk	list of strings	["/"]	mount points reported as services disk <mount>; an explicit empty list disables disk collection
net	list of strings	empty = all non-loopback interfaces, capped at 8	interface names reported in the network service
checks	list	empty	local plugin checks submitted as passive services
checks[].service	string	—	service name on the server
checks[].command	string	—	plugin path, or a bare name resolved against the plugin search path, then PATH
checks[].args	list of strings	empty	argv (no shell)
checks[].timeout	duration	30s	per-check timeout (values ≤ 0 fall back to 30 s)
pull	bool	false	fetch agent-class checks from GET /api/v1/agent/checks?host=<hostname>
pullInterval	duration	5m	re-fetch cadence of the pulled check list
pullAllow	list of strings	empty = deny all pulled checks	allow-list of bare plugin basenames that pulled checks may execute
listen	string	empty = listener off	address of the active HTTPS listener, e.g. ":5693"
listenToken	string	required when listen is set	bearer token the server must present (builtin:agent --token)
tlsCert	string	empty = self-signed at start	PEM certificate for the listener
tlsKey	string	—	PEM key, paired with tlsCert

Plugin search path for bare command names: /usr/local/bin:/usr/bin:/bin:/usr/lib/nagios/plugins:/usr/lib64/nagios/plugins:/usr/local/libexec/nagios:/opt/homebrew/bin:/opt/homebrew/sbin.

Minimal file (what Admin → Agents generates, comments omitted):

/etc/northplane/agent.yaml

server: https://northplane.example.net
token: np_…
hostname: web-01
interval: 60s
disk: ["/"]

Every key in use:

/etc/northplane/agent.yaml

server: https://northplane.example.net
token: np_0123456789abcdef0123456789abcdef0123456789abcdef
hostname: db-01
insecure: false
interval: 60s
disk: ["/", "/var/lib/postgresql"]
net: ["eth0"]
checks:
  - service: postgres
    command: check_pgsql
    args: ["-H", "127.0.0.1", "-l", "postgres"]
    timeout: 20s
pull: true
pullInterval: 5m
pullAllow: ["check_disk", "check_http", "check_pgsql"]
listen: ":5693"
listenToken: 8f1c0a6d3f8e4f9d9a7b2c1d0e5f6a7b
tlsCert: /etc/northplane/agent.crt
tlsKey: /etc/northplane/agent.key

Objects must exist first

The server rejects results for unknown hosts/services (unknown host <h>, unknown object <h>/<s>) and creates nothing automatically. Create the Host object with the agent’s hostname and the services it reports (load, memory, disk /, processes, network, cpu on Windows, plus your checks[].service names) before starting the agent — via UI, API or bundle. See Agent.

Exit codes

Exit	When	Log line
0	-version; clean shutdown on SIGINT/SIGTERM	np-agent: stopping
1	config file unreadable	config err=…
1	YAML parse error	config parse err=…
1	server or token empty after the env override	config: server and token required
1	listen set without listenToken	config: listenToken required with listen
1	listener fails to start or serve	listener err=…
2	unknown flag	Go flag usage

There is no connectivity check at startup: an unreachable server or a rejected token does not stop the agent — each tick logs a warning and buffers (see below).

Log lines

Text key=value lines on stderr, Info level and above; no log-level or format setting exists.

Level	Message	Attributes
INFO	np-agent: started	host, server, interval, checks, pull
INFO	np-agent: active listener	addr, tls=configured|self-signed
WARN	submit failed, buffering	buffered (results held in memory, max 10 000), err (e.g. HTTP 401, HTTP 403, a transport error)
WARN	pull: fetching checks failed, keeping previous set	checks, err
WARN	pull: refusing server-supplied check command	service, command, reason
INFO	np-agent: stopping	—
ERROR	config, config parse, config: server and token required, config: listenToken required with listen, listener	err

HTTP 401 means the token is invalid, HTTP 403 that it lacks objects:write (or objects:read for pull). Buffered results are re-sent in full on the next tick until one push succeeds; the buffer lives in memory and is lost on restart.

Related

• Agent — collectors and service names, push/pull/listener protocols, systemd/launchd/Windows service snippets, troubleshooting.
• API tokens — minting the objects:write token.
• REST endpoints used by the agent: post_results, get_agent_checks.