task

Tasks are operations executed on devices — they are produced by many flows (ndcli sync apply, VPN configuration, backup runs, recurring scheduled tasks, and user-initiated runs via ndcli run). The task command surface is for inspecting and cancelling them. To issue a command to one or more devices, use ndcli run. To manage recurring tasks, use ndcli schedule tasks.

Task Types

Type	Description
PING	Check device connectivity (issued by ndcli run ping)
SHUTDOWN	Power off the device (issued by ndcli run poweroff)
REBOOT	Reboot the device (issued by ndcli run restart)
RESTART	Restart the NetDefense agent service (issued by ndcli run plugin-reload)
PLUGIN_INSTALL	(Re)install the NetDefense agent plugin (issued by ndcli run plugin-install)
FIRMWARE_UPGRADE	Upgrade the device’s OPNsense firmware — a minor point release or a major series jump (issued by ndcli run firmware-upgrade)
PULL	Pull configuration from device
SYNC	Sync configuration to device
BACKUP	Run a configured backup
CONNECT	Open a remote-access tunnel session to the device

Task Statuses

Status	Description
PENDING	Task created and waiting for dispatch
SCHEDULED	Task deferred via --at; activates when its time arrives
IN_PROGRESS	Task currently executing on the device
COMPLETED	Task completed successfully
FAILED	Task failed
CANCELED	Task was cancelled before dispatch
EXPIRED	Task expired before the device picked it up

Note the spelling: the status value is CANCELED, with a single L. From ndcli 1.36.0, --status also accepts CANCELLED.

Task retention

NetDefense automatically removes finished tasks (COMPLETED, FAILED, EXPIRED and CANCELED) after 30 days. More precisely, a finished task is removed once its creation time, its expiry time and its last update are all more than 30 days in the past. PENDING, SCHEDULED and IN_PROGRESS tasks are never removed. Removal runs in the background about once an hour, so a task can stay visible a little past the 30 days.

Once removed, a task no longer appears in ndcli task list, on the Tasks page in NDWeb or on the dashboard, and looking up its task code returns “not found”. Removing a BACKUP task leaves its backup alone: backup files live in your organization’s own storage, and NetDefense does not delete them. Recurring scheduled tasks and their schedules are not affected either.

Commands

Command	Description
task list	List tasks
task describe	Show task details
task cancel	Cancel a pending or scheduled task

---

task list

List tasks in your organization.

ndcli task list [flags]

Flags

Flag	Type	Default	Description
--device	string		Filter by device name (regex)
--status	string		Filter by status. For several values, repeat the flag or separate them with commas (e.g., --status FAILED --status EXPIRED); that needs ndcli 1.36.0 or later
--type	string		Filter by task type. For several values, repeat the flag or separate them with commas (e.g., --type SYNC --type BACKUP); that needs ndcli 1.36.0 or later
--expired	bool		Filter by expired status
--created-after	string		Filter by created date
--created-before	string		Filter by created date
--sort-by	string	created_at:desc	Sort field and direction
--page	int	1	Page number
--per-page	int	30	Items per page (max 100)

Date Filter Formats

Date filters accept:

• Relative: 30m, 2h, 7d, 2w (minutes, hours, days, weeks ago)
• ISO 8601: 2024-01-15T10:30:00Z

Examples

ndcli task list

ndcli task list --created-after 1h

ndcli task list --device fw-prod-01

ndcli task list --status FAILED

ndcli task list --type SYNC

ndcli task list --status SCHEDULED --sort-by created_at:asc

# Multi-value: show both FAILED and EXPIRED tasks
ndcli task list --status FAILED --status EXPIRED

# Multi-value: show SYNC and BACKUP tasks from the last 24h
ndcli task list --type SYNC --type BACKUP --created-after 24h

---

task describe

Show detailed information about a specific task.

ndcli task describe [task-id]

Arguments

Argument	Required	Description
task-id	Yes	Task code (8-char base62)

Output

Shows:

• Task code and type
• Target device
• Status and progress
• Creation, update, expiry, and (when set) scheduled timestamps
• Result or error message

Examples

ndcli task describe abc12345
ndcli task describe abc12345 -f json

Notes

• Finished tasks are removed after 30 days; looking up a removed task’s code returns “not found”. See Task retention.

---

task cancel

Cancel a pending or scheduled task.

ndcli task cancel [task-id]

Arguments

Argument	Required	Description
task-id	Yes	Task code to cancel

Examples

ndcli task cancel abc12345

Notes

• Only tasks with PENDING or SCHEDULED status can be cancelled.
• Tasks already IN_PROGRESS cannot be cancelled.
• Cancelled tasks have status CANCELED.