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

Shared flags

Every ndcli run subcommand accepts the same target and scheduling flags. 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
--org	No (boolean)	Target every enabled device in the current organization

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

Scheduling

The --at flag defers execution. Omit it to run immediately. 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 2026-05-12 --at "2026-05-12 03:00" --at 2026-05-12T03:00:00	Interpreted in your configured timezone (see config set 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.

Bare timestamps follow your output.timezone config (default: system local). So if you ndcli config set timezone America/Sao_Paulo, then --at "2026-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.

---

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

# 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 --org --at 2026-05-12T03:00:00Z