run

ndcli run is the user-initiated command surface for the NetDefense fleet. It issues a pre-defined operation to one device, a group of devices (an OU), or every device in your organization — optionally scheduled for a later time.

Under the hood, each invocation creates one task per resolved device. To inspect or cancel those tasks afterwards, use ndcli task.

Commands

Command	Description
run ping	Ping a target IP or hostname from the device(s)
run poweroff	Power off the device(s)
run restart	Restart (reboot) the device(s)
run plugin-install	(Re)install the NetDefense agent plugin on the device
run plugin-reload	Reload (restart) the NetDefense agent service
run firmware-upgrade	Upgrade OPNsense firmware — minor point release or major series jump. A device in a firmware track is refused
run backup	Back up the configuration of the device(s) now. Only devices with backup enabled are backed up

Shared flags

Every ndcli run subcommand accepts the same target and scheduling flags, except run backup, which takes the target flags only. At least one targeting flag is required.

Target flags

Flag	Repeatable	Description
--device <name>	Yes	Target a specific device by name
--ou <name>	Yes	Target every enabled device in the OU
--all	No (boolean)	Target every enabled device in the current organization

--all is mutually exclusive with --device and --ou. Otherwise, --device and --ou may be combined freely — the final target set is the union of all resolved devices, deduped by UUID.

If any named device or OU cannot be resolved, the whole batch is rejected with a 422 error — no partial application.

--all needs ndcli 1.42.0 or later. It replaces --org with no value, which still works but prints a deprecation warning; in the next major version, --org <name> will select the organization instead, as on other commands.

run backup backs up only devices that have backup enabled, so for it --all means every device with backup enabled, not every device in the organization.

Organization

A run acts on your default organization (ndcli config set org <name>). Add -o <name>, or --organization <name>, to run in another one, as on other commands. This needs ndcli 1.42.0 or later; older versions always use the default.

Scheduling

The --at flag defers execution. Omit it to run immediately. run backup does not take it. Three input forms are accepted:

Form	Example	Meaning
Relative offset	--at 30m, --at 2h, --at 3d, --at 1w	Now + offset. Units: s, m, h, d, w.
Bare timestamp	--at 2030-05-12 --at "2030-05-12 03:00" --at 2030-05-12T03:00:00	Interpreted in your configured timezone (see config set timezone). Date-only inputs land at midnight.
Explicit timezone	--at 2030-05-12T03:00:00Z --at 2030-05-12T03:00:00-03:00	RFC3339 — exact instant, no ambiguity.

Bare timestamps follow your output.timezone config (default: system local). So if you ndcli config set timezone America/Sao_Paulo, then --at "2030-05-12 03:00" means 3 AM in São Paulo. The CLI converts to UTC before sending to the server.

Scheduled tasks are created with status SCHEDULED. NetDefense activates them (flips to PENDING) every 10 seconds when their time arrives, then dispatches normally. You can ndcli task cancel <code> a scheduled task at any time before it’s activated.

Output

Every command except run backup prints the run’s code beside the task count, then a table of its tasks, then the command that lists the run’s tasks. This needs ndcli 1.42.0 or later:

ndcli run restart --ou edge-routers -o acme

✓ Created 3 REBOOT tasks in org "acme" (run R7x2Kp9Q)
╭────────────┬──────────┬─────────────────────╮
│ Device     │ Task     │ Expires             │
├────────────┼──────────┼─────────────────────┤
│ fw-edge-01 │ 4fK9xQ2m │ 2030-05-12 03:20:00 │
│ fw-edge-02 │ Lp7cW3eZ │ 2030-05-12 03:20:00 │
│ fw-edge-03 │ 9TnB2vQa │ 2030-05-12 03:20:00 │
╰────────────┴──────────┴─────────────────────╯
List the run's tasks with: ndcli task list --run R7x2Kp9Q -o acme

A run scheduled with --at says Scheduled instead of Created, gives the time it fires, and adds a Fires at column. --schedule registers a recurring spec instead, which has no run yet.

---

run ping

Ping a target IP or hostname from the device(s).

ndcli run ping --host <target> [--count <n>] <target-flags> [--at <time>]

Flags

Flag	Required	Default	Description
--host	Yes		Target IP or hostname to ping
--count	No	4	Number of ping packets (1–1000)

Examples

# Single device
ndcli run ping --host 8.8.8.8 --device fw-prod-01

# Whole OU
ndcli run ping --host 1.1.1.1 --count 10 --ou edge-routers

# Schedule for 3 AM UTC
ndcli run ping --host 8.8.8.8 --device fw-prod-01 --at 2030-05-12T03:00:00Z

---

run poweroff

Power off the device(s). The device goes offline immediately and must be powered back on physically (or via out-of-band management).

ndcli run poweroff <target-flags> [--at <time>]

Examples

# Single device, immediate
ndcli run poweroff --device decommissioned-fw

# Maintenance-window shutdown for a whole OU at 3 AM UTC
ndcli run poweroff --ou datacenter-east --at 2030-05-12T03:00:00Z

Caution

poweroff takes the device offline with no scheduled return. Use this only when you have a way to power the device back on (PDU, IPMI, physical access).

---

run restart

Restart (reboot) the device(s). Brings the device through a full reboot cycle; service is interrupted until it comes back online.

ndcli run restart <target-flags> [--at <time>]

Examples

ndcli run restart --device fw-staging-01

ndcli run restart --ou edge-routers --at 2030-05-12T03:00:00Z

Caution

A full reboot interrupts service. Schedule with --at for production fleets.

---

run plugin-install

(Re)install the NetDefense agent plugin on one or more devices. The task completes when the agent reconnects with the expected version, or fails on mismatch / 15-minute timeout.

ndcli run plugin-install [--version <semver>] <target-flags> [--at <time>]

Flags

Flag	Default	Description
--version	(latest)	Semver to pin the install to. Empty = upgrade to the latest in the device’s installed channel.

Examples

# Upgrade everything in the org to latest
ndcli run plugin-install --all

# Pin a specific version on a subset of devices
ndcli run plugin-install --version 1.5.2 --ou edge-routers --device fw-spare-01

---

run plugin-reload

Reload (restart) the NetDefense agent service on the device(s). The device stays online; only the agent process restarts.

ndcli run plugin-reload <target-flags> [--at <time>]

Examples

ndcli run plugin-reload --device fw-prod-01

# Whole org, scheduled for the maintenance window
ndcli run plugin-reload --all --at 2030-05-12T03:00:00Z

---

run backup

Back up the configuration of the device(s) now. Only devices with backup enabled are backed up; turn it on per device with backup enable. run backup needs ndcli 1.41.0 or later; an older ndcli has no such command. See Backups.

ndcli run backup <target-flags>

It takes the target flags only, and at least one is required. --all backs up every device with backup enabled, and cannot be combined with --device or --ou. A backup starts now, so --at and --schedule are refused; recurring backups are set with ndcli backup config set --schedule <name>.

An offline device does not take the backup later. Each backup task expires about a minute after it is created, so the task of a device that stays offline ends EXPIRED.

What is skipped

A device that is not backed up is listed with the reason, in every output format, next to the tasks that were started. The reasons are:

Reason	Meaning
Backup is not enabled for this device	Turn it on with ndcli backup enable <device>.
The device is not enabled, so no task can be sent to it	The device is disabled or waiting for approval.
No backup encryption key is configured for this device	Neither the device nor the organization has an encryption key.
A backup of this device is already waiting to be sent or running	Wait for that backup to finish.
The backup could not be started for this device; try again	Run the command again.

A device named with --device, or in an OU named with --ou, that has backup off is listed. With --all, devices without backup enabled are not listed.

When no backup can start, the command fails and the error lists each device’s reason, with a hint such as ndcli backup enable <device>. It also fails when the organization has no backup configuration, or when the configuration is disabled; set it up or turn it on with backup config set and backup config enable.

Examples

# One device
ndcli run backup --device fw-prod-01

# The devices of an OU that have backup enabled
ndcli run backup --ou edge-routers

# Every device with backup enabled, then follow the tasks
ndcli run backup --all
ndcli task list --type BACKUP