Run Command

ndcli run is the operator’s tool for issuing pre-defined commands directly to firewall devices. Where sync is about propagating configuration changes, run is about operational actions — pinging a host, restarting an agent, rebooting a device, installing the plugin.

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

Every command produces one task per resolved device. Use ndcli task list and ndcli task describe to inspect them afterwards.

Picking targets

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
--org	No (boolean)	Target every enabled device in the current organization

--org is mutually exclusive with --device and --ou.

# 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 --org

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

Scheduling with --at

Add --at to any run command to defer execution. 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 2026-05-12 --at "2026-05-12 03:00" --at 2026-05-12T03:00:00	Interpreted in your configured timezone. Date-only inputs land at midnight.
Explicit timezone	--at 2026-05-12T03:00:00Z --at 2026-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 tomorrow in your local time
ndcli run poweroff --device decommissioned-fw --at "2026-05-13 03:00"

# Upgrade the agent fleet during the next maintenance window (UTC, explicit)
ndcli run plugin-install --version 1.5.2 --org --at 2026-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 scheduled tasks work

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

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.

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 "2026-05-13 03:00"

Reboots every device in edge-routers at 3 AM tomorrow 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, tomorrow at 3 AM
ndcli run plugin-install --version 1.5.2 --ou production --at "2026-05-13 03:00"

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.