software

Software policy management commands for NDCLI. A software policy is a reusable, named list of OPNsense plugins and FreeBSD packages NetDefense will install (present) or uninstall (absent) on every device that picks the policy up through its templates.

See the Software Policies concept page for the full picture: content shape, conflict resolution (presence wins), reconciliation order (uninstall before install), and per-package action codes.

Content shape

Software policy content is JSON:

{
  "present": ["os-zabbix72-agent", "bash"],
  "absent":  ["os-zabbix6-agent", "os-zabbix74-agent"]
}

• Either list may be empty ([]).
• Names must match ^[A-Za-z0-9][A-Za-z0-9._+-]*$ (no spaces, no shell metacharacters), at most 100 characters.
• Each list is capped at 200 entries.
• A single document may not list the same name twice in one list or in both lists; cross-policy conflicts are resolved later by “presence wins”.

Commands

software list

List software policies in an organization.

ndcli software list [flags]

Flags

Flag	Default	Description
--name	—	Filter by name (regex pattern)
--sort-by	name:asc	Sort field and direction (name, created_at, updated_at)
--page	1	Page number
--per-page	50	Items per page (max 100)

Examples

ndcli software list

ndcli software list --name "monitoring-*"

ndcli software list -f json | jq '.software_policies[].name'

---

software describe

Show a software policy’s metadata, full JSON content, and the list of templates this policy is currently attached to.

ndcli software describe [name]

Arguments

Argument	Required	Description
name	Yes	Software policy name

Output

In addition to the package counts, describe includes a Templates line (label/value in detailed and simple, extra column in table, template_names field in json) listing every template the policy is attached to. (none) is shown when the policy isn’t attached anywhere yet. This field is populated on describe only — software list keeps the request cheap and omits it.

Examples

ndcli software describe monitoring-tools
ndcli software describe monitoring-tools -f json   # template_names is a string[]

---

software create

Create a new software policy. The policy is created empty when no content is supplied — use require-package / block-package to populate it. The --content / --file flags are for bulk seeding only.

ndcli software create [name]                              # empty by default
ndcli software create [name] (--content '...' | --file ./file.json)  # bulk seed

Arguments

Argument	Required	Description
name	Yes	New software policy name

Flags

Flag	Required	Description
--content	No	Inline JSON content (bulk-seed alternative)
--file	No	Path to a file containing the JSON content (bulk-seed alternative)

Examples

# Empty (typical)
ndcli software create monitoring-tools

# Bulk seed inline
ndcli software create monitoring-tools \
  --content '{"present": ["os-zabbix72-agent", "bash"], "absent": ["os-zabbix6-agent"]}'

# Bulk seed from a file
ndcli software create monitoring-tools --file ./policies/monitoring-tools.json

---

software edit

Edit a software policy’s content in an external editor (the $EDITOR env var). The content is pretty-printed before editing; a save that only re-indents is treated as a no-op.

ndcli software edit [name]

---

software update-content

Replace a software policy’s content from a file.

ndcli software update-content [name] [file]

Arguments

Argument	Required	Description
name	Yes	Software policy name
file	Yes	Path to file containing new JSON content

Examples

ndcli software update-content monitoring-tools ./policies/monitoring-tools.json

---

software rename

Rename a software policy. Templates attached to the policy keep their attachment.

ndcli software rename [name] [new-name]

Examples

ndcli software rename monitoring-tools monitoring-tools-v2

---

software delete

Delete a software policy. Templates attached to it lose the package inventory on their next sync; already-installed packages stay on the device unless they’re also covered by another policy’s absent list.

ndcli software delete [name]

Examples

ndcli software delete monitoring-tools

---

software require-package

Add one or more packages to a policy’s required list. Required packages get installed on every device the policy covers.

ndcli software require-package [policy] [package...]

Arguments

Argument	Required	Description
policy	Yes	Software policy name
package	Yes	One or more package names (variadic)

Behavior

• A package already required is an idempotent no-op (printed with ℹ).
• A package currently in the blocked list is moved (↻ Required: <name> (was: blocked)).
• The change is atomic: if the server rejects one name, no changes are applied.

Examples

# Single package
ndcli software require-package monitoring-tools os-zabbix72-agent

# Bulk
ndcli software require-package monitoring-tools os-zabbix72-agent bash vim

---

software block-package

Add one or more packages to a policy’s blocked list. Blocked packages get uninstalled on every device the policy covers.

ndcli software block-package [policy] [package...]

Arguments

Argument	Required	Description
policy	Yes	Software policy name
package	Yes	One or more package names (variadic)

Behavior

• A package already blocked is an idempotent no-op.
• A package currently required is moved (↻ Blocked: <name> (was: required)).
• The change is atomic.

Examples

ndcli software block-package monitoring-tools os-zabbix6-agent os-zabbix74-agent

---

software waive-package

Remove one or more packages from whichever list (required or blocked) they sit in. Waive does not uninstall or re-install anything on devices — it just stops the policy from caring.

ndcli software waive-package [policy] [package...]

Arguments

Argument	Required	Description
policy	Yes	Software policy name
package	Yes	One or more package names (variadic)

Behavior

• Each outcome reports what the package was: ✓ Waived: bash (was: required) or ✓ Waived: nano (was: blocked).
• A package not specified in either list is a no-op.

Examples

# Stop caring about two packages — regardless of which list they're in
ndcli software waive-package monitoring-tools bash os-zabbix6-agent

---

Attaching a software policy to a template

Software policies attach to templates the same way snippets do, using the template subcommands:

ndcli template add-software network-monitoring monitoring-tools
ndcli template remove-software network-monitoring monitoring-tools

See ndcli template for the full template command surface.