snippet

Snippet management commands for NDCLI. Snippets are reusable configuration blocks that define users, groups, aliases, and firewall rules. Snippets are combined into templates to create complete configurations.

Snippet Types

Snippet content is JSON for every type. NDAgent talks to OPNsense through its REST API for all of them; each snippet’s content is the JSON payload the agent will hand to the matching OPNsense endpoint.

Type	Description
USER	User definition (OPNsense auth/user)
GROUP	Group definition (OPNsense auth/group)
ALIAS	Network alias — host, network, or port set (OPNsense firewall/alias)
RULE	Firewall rule (OPNsense firewall/filter)
UNBOUND_HOST_OVERRIDE	Unbound DNS host override — A/AAAA/MX/TXT record
UNBOUND_DOMAIN_FORWARD	Unbound DNS domain forwarding (incl. DoT)
UNBOUND_HOST_ALIAS	Unbound DNS host alias (CNAME-style, references a host override)
UNBOUND_ACL	Unbound DNS query ACL
ZABBIX_SETTINGS	Zabbix Agent global settings — singleton; NDAgent owns the full local/main/tuning/features tree on every apply
ZABBIX_USERPARAMETER	Zabbix UserParameter (custom check command). Key must start with nd-
ZABBIX_ALIAS	Zabbix item-key alias. Key must start with nd-

Commands

Command	Description
snippet list	List snippets
snippet describe	Show snippet details
snippet create	Create a new snippet
snippet delete	Delete a snippet
snippet edit	Edit snippet in external editor
snippet pull	Pull snippet from a device
snippet rename	Rename a snippet
snippet set-priority	Set snippet priority
snippet update-content	Update snippet content from file

---

snippet list

List snippets in your organization.

ndcli snippet list [flags]

Flags

Flag	Type	Default	Description
--name	string		Filter by name (regex pattern)
--type	string		Filter by type: USER, GROUP, ALIAS, RULE, UNBOUND_HOST_OVERRIDE, UNBOUND_DOMAIN_FORWARD, UNBOUND_HOST_ALIAS, UNBOUND_ACL, ZABBIX_SETTINGS, ZABBIX_USERPARAMETER, ZABBIX_ALIAS
--created-after	string		Filter by created date
--created-before	string		Filter by created date
--updated-after	string		Filter by updated date
--updated-before	string		Filter by updated date
--sort-by	string	priority:asc	Sort field: priority, name, created_at, updated_at
--page	int	1	Page number
--per-page	int	50	Items per page (max 100)

Examples

ndcli snippet list

ndcli snippet list --type RULE

ndcli snippet list --type ALIAS

ndcli snippet list --name "admin.*"

ndcli snippet list --updated-after 24h

ndcli snippet list --sort-by name:asc

---

snippet describe

Show detailed information about a snippet including its content.

ndcli snippet describe [name]

Arguments

Argument	Required	Description
name	Yes	Snippet name

Output

Shows:

• Snippet name and type
• Priority
• Full content
• Creation and update timestamps
• Templates using this snippet

Examples

ndcli snippet describe admin-users
ndcli snippet describe firewall-rules -f json

---

snippet create

Create a new snippet.

ndcli snippet create [name] [flags]

Arguments

Argument	Required	Description
name	Yes	Snippet name

Flags

Flag	Type	Default	Description
--type	string	Required	Snippet type: USER, GROUP, ALIAS, RULE, UNBOUND_HOST_OVERRIDE, UNBOUND_DOMAIN_FORWARD, UNBOUND_HOST_ALIAS, UNBOUND_ACL, ZABBIX_SETTINGS, ZABBIX_USERPARAMETER, ZABBIX_ALIAS
--content	string		Snippet content (inline)
--file	string		Read content from file
--priority	int	1000	Priority (1-60000, lower = higher priority)

Examples

ndcli snippet create web-servers \
  --type ALIAS \
  --content "host web1 { 192.168.1.10 }
host web2 { 192.168.1.11 }"

ndcli snippet create firewall-rules \
  --type RULE \
  --file ./rules.conf

ndcli snippet create critical-rules \
  --type RULE \
  --file ./critical.conf \
  --priority 100

Priority Guidelines

Priority determines the order snippets are applied (lower numbers = higher priority):

Range	Suggested Use
1-500	Critical/foundational rules
500-1000	Core infrastructure
1000-2000	Standard configurations
2000-5000	Application-specific rules
5000+	Optional/override rules

---

snippet delete

Delete a snippet.

ndcli snippet delete [name]

Arguments

Argument	Required	Description
name	Yes	Snippet name to delete

Examples

ndcli snippet delete deprecated-rules

Caution

Deleting a snippet removes it from all templates that use it. Check template assignments with ndcli snippet describe before deleting.

---

snippet edit

Open a snippet’s content in your system’s default text editor for editing.

ndcli snippet edit [name]

Arguments

Argument	Required	Description
name	Yes	Snippet name

How It Works

1. Downloads current snippet content to a temporary file
2. Opens the file in your default editor ($EDITOR or system default)
3. After you save and close, uploads the modified content
4. If no changes were made, no update occurs

Environment Variables

Variable	Description
EDITOR	Preferred text editor (e.g., vim, nano, code)
VISUAL	Alternative editor variable

Examples

ndcli snippet edit firewall-rules

EDITOR=nano ndcli snippet edit firewall-rules

---

snippet pull

Pull configuration content from a device and optionally save it as a snippet.

ndcli snippet pull [device] [snippet-name] [flags]

Arguments

Argument	Required	Description
device	Yes	Device name to pull from
snippet-name	Yes	Name for the pulled content

Flags

Flag	Type	Default	Description
--type	string	ALIAS	Config type to pull (see match semantics below): USER, GROUP, ALIAS, RULE, UNBOUND_HOST_OVERRIDE, UNBOUND_DOMAIN_FORWARD, UNBOUND_HOST_ALIAS, UNBOUND_ACL, ZABBIX_SETTINGS, ZABBIX_USERPARAMETER, ZABBIX_ALIAS
--auto-create	bool	false	Create snippet in DB if it doesn’t exist
--overwrite	bool	false	Update snippet if it already exists
--wait	-w	false	Wait for task to complete

Examples

ndcli snippet pull fw-prod-01 production-aliases --type ALIAS

ndcli snippet pull fw-prod-01 production-aliases --type ALIAS --wait

ndcli snippet pull fw-prod-01 new-rules \
  --type RULE \
  --auto-create \
  --wait

ndcli snippet pull fw-prod-01 existing-aliases \
  --type ALIAS \
  --overwrite \
  --wait

Match Semantics

The snippet-name argument doubles as the lookup key on the device. How it’s interpreted depends on --type:

Type	Lookup
USER	exact username
GROUP	exact group name
ALIAS	exact alias name
RULE	partial description match (case-insensitive); fails if multiple match
UNBOUND_HOST_OVERRIDE	hostname.domain (e.g. server1.local)
UNBOUND_DOMAIN_FORWARD	domain name (e.g. internal.corp)
UNBOUND_HOST_ALIAS	hostname.domain (e.g. www.local)
UNBOUND_ACL	ACL name (e.g. lan-clients)
ZABBIX_SETTINGS	singleton — name is the destination snippet name only; the agent returns the full Zabbix Agent settings tree
ZABBIX_USERPARAMETER	exact UserParameter key (e.g. nd-cpu-temp)
ZABBIX_ALIAS	exact item-alias key (e.g. nd-uname)

Async Behavior

By default, snippet pull creates an asynchronous task and returns immediately with a task ID. Use --wait to block until completion, or check task status with:

ndcli task describe <task-id>

---

snippet rename

Rename a snippet.

ndcli snippet rename [name] [new-name]

Arguments

Argument	Required	Description
name	Yes	Current snippet name
new-name	Yes	New snippet name

Examples

ndcli snippet rename old-rules new-rules

---

snippet set-priority

Change a snippet’s priority.

ndcli snippet set-priority [name] [priority]

Arguments

Argument	Required	Description
name	Yes	Snippet name
priority	Yes	New priority (1-60000)

Examples

ndcli snippet set-priority critical-rules 100

ndcli snippet set-priority optional-rules 5000

---

snippet update-content

Update a snippet’s content from a file.

ndcli snippet update-content [name] [file]

Arguments

Argument	Required	Description
name	Yes	Snippet name
file	Yes	Path to file containing new content

Examples

ndcli snippet update-content firewall-rules ./updated-rules.conf

cat new-content.conf | ndcli snippet update-content my-snippet /dev/stdin