sync

Synchronization commands for NDCLI. These commands help you monitor and trigger configuration synchronization to devices.

Overview

Configuration sync ensures that devices receive and apply the latest configuration from their assigned templates. Sync status shows whether devices are up-to-date with their expected configuration.

Commands

Command	Description
sync status	Show sync status for devices
sync apply	Trigger sync for devices

---

sync status

Show synchronization status for devices.

ndcli sync status [flags]

Flags

Flag	Type	Default	Description
--device	string		Filter by device name (regex pattern)
--ou	string		Filter by organizational unit (exact name)
--template	string		Filter by template name (regex pattern) — devices whose effective OU→Template chain matches
--org	string	current org	Filter by organization (exact name)
--drift-status	string		Filter by drift status: IN_SYNC, DRIFT, NEVER_SYNCED, UNKNOWN, ERROR

--device and --template are regular expressions; --org and --ou match exact names.

Output

Shows for each device:

• Device name
• Organizational unit
• Sync status (synced/pending/error)
• Drift status
• Last sync timestamp
• Configuration version

A device whose configuration can’t be built shows ERROR; with -f json the reason is in its error field. When no device matches, -f json prints {"items": [], "total": 0} and the other formats print ℹ No devices found.

Sync States

State	Description
Synced	Device has the latest configuration
Pending	Device needs to sync new configuration
Error	Last sync attempt failed
Never	Device has never synced

Examples

ndcli sync status

ndcli sync status --device fw-prod-01

ndcli sync status --ou production

ndcli sync status --device "fw-.*-01"

ndcli sync status --drift-status DRIFT

ndcli sync status --drift-status DRIFT --ou production

---

sync apply

Trigger configuration sync for one or more devices.

ndcli sync apply [flags]

Flags

Flag	Type	Default	Description
--device	string		Sync devices matching pattern (regex)
--ou	string		Sync all devices in the OU with this exact name
--template	string		Sync devices whose effective OU→Template chain matches the template name (regex)
--org	string	current org	Filter by organization (exact name)
--drift-status	string		Only sync devices with the given drift status: IN_SYNC, DRIFT, NEVER_SYNCED, UNKNOWN, ERROR
--schedule	string		Attach a named schedule — creates a recurring sync task instead of a one-time sync
--force	bool	false	Force sync even if already synced
--yes	-y	false	Skip confirmation prompt

Examples

ndcli sync apply --device fw-prod-01

ndcli sync apply --ou production

ndcli sync apply --ou branch-offices

ndcli sync apply --device "fw-datacenter-.*"

ndcli sync apply --template edge-firewall-v2

ndcli sync apply --template "^edge-.*" --yes

ndcli sync apply --device fw-prod-01 --force

ndcli sync apply --ou staging --yes

ndcli sync apply --drift-status DRIFT

ndcli sync apply --drift-status DRIFT --yes

Confirmation

By default, sync apply asks for confirmation before triggering syncs. Use --yes or -y to skip:

ndcli sync apply --ou production -y

The device list and the prompt go to standard error, so with -f json standard output carries only the result.

Devices that can’t be built

A device whose configuration can’t be built gets no task. sync apply lists it under Errors with the reason, and with the error’s code in brackets when it has one; with -f json, each entry has a code field. When every device fails, the command exits 1.

Errors:
  • fw-hq-01: [SNIPPET_UUID_CONFLICT] More than one snippet on this device carries the same uuid: 221f3268-4ac9-4cb3-aad3-63a0f8c09585 (snippets: web-servers, web-servers-copy; templates: branch, edge). Keep one snippet per uuid: edit each extra snippet and give it a new managed uuid (221f3268-xxxx-4xxx-yxxx-xxxxxxxxxxxx in lowercase hex, y one of 8, 9, a or b); its templates and priority stay as they are

When a configuration can’t be built lists the common causes. For a shared uuid, The managed uuid has the fix, and a caution for ALIAS snippets.

Force Sync

Normally, devices that are already synced are skipped. Use --force to re-sync all matched devices:

ndcli sync apply --ou production --force

Combining Filters

You can combine --device, --ou, and --template to narrow the scope (filters compose via AND):

ndcli sync apply --ou production --device "fw-web-.*"

ndcli sync apply --template edge-firewall-v2 --ou production

Template-scoped sync

Templates can be attached to multiple OUs. --template selects every device whose effective Device → OU → Template chain includes a template matching the regex, so you can sync “everything affected by template X” without enumerating its OUs:

ndcli sync status --template '^edge-firewall-.*'

ndcli sync apply --template edge-firewall-v2 -y

Scheduling a recurring sync

Pass --schedule <name> to create a scheduled task that runs the sync automatically on the named cadence:

ndcli sync apply --ou branch-offices --schedule nightly-maintenance

ndcli sync apply --drift-status DRIFT --schedule monday-reboot

Use ndcli schedule tasks list to manage recurring syncs.

Typical Workflow

ndcli sync status --ou production

ndcli sync apply --ou production

ndcli sync status --ou production

ndcli task list --type SYNC --created-after 5m