device

Device management commands for NDCLI. These commands allow you to list, approve, rename, and remove firewall devices in your organization.

Commands

Command	Description
device list	List devices
device describe	Show device details
device health	Show the device’s instantaneous health snapshot
device connect	Connect to a device through the connection relay
device approve	Approve a pending device
device approve-all	Approve all pending devices
device rename	Rename a device
device remove	Remove a device
device rebind-token	Issue a one-time re-bind token for the device’s signing key

---

device list

List devices in your organization with optional filtering and sorting.

ndcli device list [flags]

Flags

Flag	Type	Default	Description
--name	string		Filter by name (regex pattern)
--status	string		Filter by status: PENDING, ENABLED, DISABLED
--ou	string		Filter by organizational unit
--created-after	string		Filter by created date
--created-before	string		Filter by created date
--heartbeat-after	string		Filter by last heartbeat
--heartbeat-before	string		Filter by last heartbeat
--synced-after	string		Filter by last sync
--synced-before	string		Filter by last sync
--drift-status	string		Filter by drift status: IN_SYNC, DRIFT, NEVER_SYNCED, UNKNOWN, ERROR
--sort-by	string	name:asc	Sort field and direction
--page	int	1	Page number
--per-page	int	30	Items per page

Date Filter Formats

Date filters accept two formats:

1. Relative: 30m, 2h, 7d, 2w (minutes, hours, days, weeks ago)
2. ISO 8601: 2024-01-15T10:30:00Z. A time with an offset, such as 2024-01-15T10:30:00-03:00, is converted. A time without an offset, or a date alone, is read as UTC

From ndcli 1.40.0, a relative time is counted from the current moment whatever timezone your computer is set to. Earlier releases moved the window by the computer’s offset from UTC.

Sort Fields

Available sort fields: name, status, created_at, heartbeat, synced_at, drift_status

Direction: asc or desc (e.g., name:asc, created_at:desc)

Examples

ndcli device list

ndcli device list --status PENDING

ndcli device list --ou production

ndcli device list --heartbeat-before 7d

ndcli device list --created-after 24h

ndcli device list --name "fw-.*-prod"

ndcli device list --sort-by heartbeat:desc

ndcli device list --page 2 --per-page 50

ndcli device list --drift-status DRIFT

ndcli device list --drift-status DRIFT --ou production

---

device describe

Show detailed information about a specific device.

ndcli device describe [device]

Arguments

Argument	Required	Description
device	Yes	Device name

Output

Shows comprehensive device information:

• Device name and UUID
• Status (PENDING, ENABLED, DISABLED)
• Whether it’s online now (online, offline, or unknown)
• Organizational unit assignment
• Last heartbeat timestamp
• Last sync timestamp and hash
• Drift status (IN_SYNC, DRIFT, NEVER_SYNCED, UNKNOWN, ERROR)
• Creation date
• Hardware/software details

Examples

ndcli device describe my-firewall

ndcli device describe my-firewall -f json

---

device health

Show a device’s latest telemetry: uptime, load, memory and swap, disk use, OPNsense service states, pending updates and certificate expiry.

ndcli device health [device]

Arguments

Argument	Required	Description
device	Yes	Device name

Output

A header gives the device’s status and whether it’s online, its agent version, the age of its last heartbeat and of its last telemetry, its OUs and its sync state. Below it:

• Resources: uptime, CPU count, load averages over 1, 5 and 15 minutes, memory use and, when the device has swap, swap use.
• Disks: use per mount point.
• Services: how many OPNsense services are running, and which ones aren’t.
• Updates: the update status, the last check, how many packages are pending, and whether a reboot is required.
• Certificates: the days left on each certificate, flagged at 30 days or fewer and shown as expired once past, and whether it’s in use.

The data is live, with no history. It refreshes with each heartbeat, every 60 seconds, and the agent re-reads services, updates and certificates every 15 minutes. A device that hasn’t reported for about 3 minutes prints No recent telemetry. under the header; the web app’s device page keeps its last report instead.

Examples

ndcli device health my-firewall

ndcli device health my-firewall -f json

---

device connect

Connect to a device interactively through the NetDefense connection relay. Opens an interactive PTY shell on the device and, unless --no-webadmin is set, a local WebAdmin tunnel to the device’s web interface on an automatically assigned port. The WebAdmin tunnel stays open after the shell exits, until you press Ctrl-C at the keep-alive prompt.

ndcli device connect [device] [flags]

Arguments

Argument	Required	Description
device	Yes	Device name

Flags

Flag	Type	Default	Description
--timeout	duration	5m	Connection timeout
--webadmin-port	int	auto	Local port for the WebAdmin tunnel
--no-webadmin	bool	false	Disable the WebAdmin tunnel
--webadmin-only	bool	false	Skip the interactive terminal and keep the WebAdmin tunnel open until you quit with Ctrl-C

Examples

# Connect with default settings
ndcli device connect my-firewall

# Connect with a custom timeout
ndcli device connect my-firewall --timeout 15m

# Connect without the WebAdmin tunnel
ndcli device connect my-firewall --no-webadmin

# Open only the WebAdmin tunnel, with no terminal
ndcli device connect my-firewall --webadmin-only

# Connect with the WebAdmin tunnel on a specific port
ndcli device connect my-firewall --webadmin-port 8443

Notes

• device connect falls back to --webadmin-only on its own when the device refuses a terminal, as in a read-only session, or when its output isn’t a terminal. When its output isn’t a terminal it doesn’t print the tunnel’s local URL, so set --webadmin-port to know where it listens.
• device connect needs an interactive login, from ndcli auth login. With NDCLI_TOKEN set, the control plane refuses the session with 400 and JWT must contain jti claim for session tracking: a personal access token can’t open a remote session. NDCLI_TOKEN takes precedence over a cached login (see How NDCLI picks a credential), so unset it, then run ndcli auth login if you have no cached session.

---

device approve

Approve a pending device, allowing it to receive configurations and participate in the organization.

ndcli device approve [device]

Arguments

Argument	Required	Description
device	Yes	Device name to approve

Examples

ndcli device approve new-firewall

Notes

• Approves a device waiting for approval: PENDING, or UNREGISTERED after a re-bind. A device that is already ENABLED is left as it is.
• Refused with 409 DEVICE_REBIND_PENDING while the device hasn’t registered its key: its rebind token is still unused, or it has no key bound. Wait for it to register with the token, or issue a new token with ndcli device rebind-token if that one has expired.
• After approval, the device status changes to ENABLED
• Approved devices can receive configuration syncs

---

device approve-all

Approve all pending devices in the organization at once.

ndcli device approve-all

Examples

ndcli device approve-all

Caution

This approves all pending devices without individual confirmation. Review pending devices with ndcli device list --status PENDING before running.

---

device rename

Rename a device.

ndcli device rename [device] [new-name]

Arguments

Argument	Required	Description
device	Yes	Current device name
new-name	Yes	New name for the device

Examples

ndcli device rename old-name new-name

Notes

• Device names must be unique within the organization
• The rename takes effect immediately
• The device UUID remains unchanged

---

device remove

Remove a device from the organization.

ndcli device remove [device]

Arguments

Argument	Required	Description
device	Yes	Device name to remove

Examples

ndcli device remove decommissioned-firewall

Danger

Permanently deletes the device. On its next contact the device removes all NetDefense-managed configuration (firewall rules, aliases, VPN, users, external authentication servers, certificates and CAs, package repositories) except certificates and CAs still in use by a service, uninstalls the NetDefense agent and repository, and cannot be restored. Re-adding it requires a fresh installation.

It also cannot be re-bound — there’s no partial-restore path once the device record is gone. Packages installed on the device through a software policy are left installed; NetDefense stops tracking them but does not uninstall them. If the device is offline, this happens the next time it reconnects — until then it simply can’t connect.

To add the same firewall back, run the installer again with the organization’s registration token and approve it as a new device. It comes back with no history from the previous registration. See Remove a Device for details.

---

device rebind-token

Issue a one-time Re-bind Token for a device: the first step of re-binding its signing key.

ndcli device rebind-token [device] [flags]

Arguments

Argument	Required	Description
device	Yes	Device name

Flags

Flag	Type	Default	Description
--ttl	duration	24h	How long the token stays valid, at most 7 days (168h)

Examples

# Issue a token valid for 24 hours
ndcli device rebind-token fw-branch-01

# Issue a token valid for 3 days
ndcli device rebind-token fw-branch-01 --ttl 72h

Notes

• The token is printed once and can’t be recovered: NetDefense keeps only a hash of it. Running the command again issues a new token, and the earlier one stops working.
• With -f json, the token is in bootstrap_token and its expiry in expires_at.
• The device drops to UNREGISTERED as soon as the token is issued, because NetDefense clears its registered public key. It stays there until the agent registers a new key with the token and you approve the device with device approve.
• --ttl takes hours, minutes or seconds (72h, 90m); there is no day unit. A value above 168h is refused.
• Needs the Read-Write or Superuser role.
• Where to paste the token on the device, and the rest of the procedure: Re-binding.