Run Command

Run is the operator’s tool for issuing pre-defined commands directly to firewall devices, from the Run page in the web console or with ndcli run. Where sync is about propagating configuration changes, run is about operational actions — pinging a host, restarting an agent, rebooting a device, installing the plugin, backing up a configuration.

A run command can target one device, a group of devices (an Organizational Unit), or every device in your organization. It can fire immediately, or be scheduled for a future time — useful for coordinated maintenance windows.

The commands

Command	What it does	When to use it
ndcli run ping	Pings a target IP/hostname from the device	Validate network reachability from the device’s perspective
ndcli run poweroff	Powers off the device	Decommissioning, deep maintenance
ndcli run restart	Reboots the device	Recover from an unhealthy state, finalize a kernel/OPNsense update
ndcli run plugin-install	(Re)installs the NetDefense agent plugin on the device’s firewall	Upgrade an agent, recover from a corrupted install
ndcli run plugin-reload	Restarts the NetDefense agent service on the device	Pick up a config tweak without a full reboot
ndcli run firmware-upgrade	Upgrades OPNsense firmware — minor point release or major series jump	Keep managed firewalls current; supports no-downtime split-apply for minor upgrades. A device in a firmware track is refused: its track moves it
ndcli run backup	Backs up the device’s configuration now, to your organization’s backup storage. Only devices with backup enabled are backed up	Take a backup before a risky change, without waiting for the schedule

Every command produces one task per resolved device (run backup produces one per device it backs up). Use ndcli task list and ndcli task describe to inspect them afterwards. From ndcli 1.42.0, every command except run backup also prints its run code and the ndcli task list --run <code> command that lists the run’s tasks.

Picking targets

Web

In the Target box on Run, choose Devices and OUs to combine OUs and single devices, or Entire organization for every enabled device, including devices that join before the run is dispatched. See Target.

CLI

Every run subcommand accepts the same three target flags. At least one is required, and --device and --ou are repeatable. The resolved target set is the union of everything you specify, deduped by device.

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. --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. To run in an organization other than your default, add -o <name> (also ndcli 1.42.0 or later).

# A single device
ndcli run plugin-reload --device fw-prod-01

# Two devices
ndcli run plugin-reload --device fw-prod-01 --device fw-prod-02

# Everything in two OUs
ndcli run plugin-reload --ou edge-routers --ou datacenter-east

# Mix of devices and OUs — union is computed server-side
ndcli run plugin-reload --ou edge-routers --device fw-spare-01

# Whole organization
ndcli run plugin-reload --all

If any named device or OU can’t be resolved, the whole batch is rejected with a clear error — there’s no partial application. Offline devices are still valid targets; their tasks sit PENDING until they reconnect (or expire). A backup is the exception: its task expires about a minute after it is created.

ndcli run backup backs up only devices that have backup enabled. With --all it means every device with backup enabled, not every device in the organization. A device you name, or a member of an OU you name, that has backup off is listed as skipped, with the reason.

Scheduling with --at and --schedule

One-time scheduling with --at

Web

Choose Later in the Schedule box on Run and type the time: an offset such as 30m or 2h, a date and time in your display timezone, or a timestamp with its own zone (RFC3339). Backup can’t be deferred. See Schedule.

CLI

Add --at to any run command except backup to defer execution once. The CLI accepts three input styles:

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. 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.

# Reboot the whole edge OU in two hours
ndcli run restart --ou edge-routers --at 2h

# Power off a device at 3 AM on 13 May 2030, in your local time
ndcli run poweroff --device decommissioned-fw --at "2030-05-13 03:00"

# Upgrade the agent fleet during the next maintenance window (UTC, explicit)
ndcli run plugin-install --version 1.5.2 --all --at 2030-05-15T03:00:00Z

Which timezone is “local”?

The bare-timestamp form uses your NDCLI display timezone, which you can inspect and set:

ndcli config show
ndcli config set timezone America/Sao_Paulo

If unset, NDCLI uses your system’s local timezone. The CLI always converts to UTC before sending to the server — the timezone setting is purely for input parsing and output display.

How one-time scheduled tasks work

A one-time scheduled task is created with status SCHEDULED. NetDefense polls every 10 seconds for scheduled tasks whose time has arrived and flips them to PENDING, at which point the normal dispatch path kicks in. You can ndcli task cancel <code> at any time before activation.

Recurring scheduling with --schedule

Web

Choose On schedule in the Schedule box on Run, pick a schedule, and click Register. The recurring spec shows on the Scheduled specs tab of Tasks.

CLI

To run a command automatically on a repeating cadence, attach a schedule instead of --at:

# Reboot the staging OU every Monday at 04:00 Chicago time
ndcli run restart --ou staging --schedule monday-reboot

# Run a weekly plugin-install across the whole org
ndcli run plugin-install --version 2.1.0 --all --schedule weekly-maintenance

This creates a scheduled task that fires on every tick of the named schedule. Use ndcli schedule tasks list to see it and ndcli schedule tasks disable <code> to pause it.

Caution

A scheduled task targets the device list at the moment it runs, not when it was created. If you add devices to an OU after scheduling ndcli run ... --ou edge-routers --at 1d, the new devices are not included — the fan-out happened at create time.

Note

ndcli run backup is exempt from both --at and --schedule: a backup starts now, and the command refuses either flag. For recurring backups, attach a schedule to the backup configuration with ndcli backup config set --schedule <name>. See Back up now.

Common patterns

Validate connectivity before a config push

ndcli run ping --host 8.8.8.8 --count 5 --ou edge-routers
ndcli task list --type PING --status COMPLETED

Run ping first to confirm every device in the OU is reachable, then sync apply knowing the network path is healthy.

Schedule a maintenance reboot

ndcli run restart --ou edge-routers --at "2030-05-13 03:00"

Reboots every device in edge-routers at 3 AM on 13 May 2030, in your configured timezone. Operators can sleep; the broker takes care of it.

Roll out an agent upgrade in waves

# Wave 1 — canary on a single device, now
ndcli run plugin-install --version 1.5.2 --device fw-canary-01

# Wave 2 — staging OU, in 1 hour
ndcli run plugin-install --version 1.5.2 --ou staging --at 1h

# Wave 3 — production, in 1 day
ndcli run plugin-install --version 1.5.2 --ou production --at 1d

Each wave produces its own batch of tasks you can monitor independently.

Cancel a scheduled batch

# Find the scheduled tasks
ndcli task list --status SCHEDULED

# Cancel one
ndcli task cancel <task-code>

Cancelling individual tasks is per-task today; bulk cancel is on the roadmap.

Run vs Task

The line is intentional and worth internalizing:

• ndcli run is the operator’s verb. You’re choosing to do something to a device.
• ndcli task is the inspection surface. Tasks come from many places — sync apply, scheduled backups, VPN config changes, and run itself. task list/describe/cancel lets you see what’s queued and what happened.

If you were previously using ndcli task create to ping devices or reboot them — that command has been removed. Use ndcli run instead.

Reference

The full per-command flag list and JSON output examples live in the run reference page.