command reference

Pre-Alpha. This page describes behavior that may change.

Ze commands fall into two categories. Shell commands run locally from the terminal. Runtime commands are sent to the running daemon over SSH. A few ze show subcommands run locally without touching the daemon (version, bgp decode, bgp encode, env, schema, yang, completion); the rest go through the SSH server built into the daemon.

This page is the wiki view of the command set. The canonical, full reference (every command, every flag, every exit code) is the in-tree command reference. When this page and that one disagree, the in-tree page wins.

Conventions

Every command that takes a filename argument accepts - as an alias for stdin when reading and stdout when writing, so configs and data stream through pipes without temp files:

generate | ze config show -                 # read a config from stdin
ssh host cat rib.mrt | ze analyze show -     # analyse an MRT streamed in
ze config show - | ze config set - bgp session asn local 65001 | ze config validate -
ze config migrate -o - old.conf              # write the migrated config to stdout

stdin can be consumed once: a second - in a single command fails with a clear error rather than reading empty. A file literally named - is addressed as ./-. Interactive or history-dependent editor commands (ze config edit, ze config rollback, ze config history) reject -, because they need a TTY or on-disk revision history a pipe does not have.

ze

Start the daemon or dispatch to a subcommand.

ze                         # No args in a terminal: interactive hierarchical TUI command launcher
ze <config-file>           # Start the daemon with a config file
ze start                   # Start from the database

With no arguments in an interactive terminal, ze opens a filterable command menu grouped by section (Up/Down navigate, Enter select or descend, Left/Backspace go back, Esc clears the filter then quits). Piped or non-interactive invocation prints static help and exits non-zero.

Flag	Purpose
-d, --debug	Enable debug logging (ze.log=debug).
-f <file>	Use filesystem storage, bypass the blob store.
--plugin <name>	Load a plugin before starting (repeatable).
--plugins	List the plugins compiled into this binary.
--pprof <addr:port>	Start a pprof HTTP server.
-V, --version	Show the version. Same as ze show version.
--chaos-seed <N>	Chaos PRNG seed (0 off, -1 time-based).
--chaos-rate <0-1>	Chaos fault probability per operation.
--server <host:port>	Override the hub address for managed mode.
--name <name>	Override the client name for managed mode.
--token <token>	Override the auth token for managed mode.
--no-color / --color	Disable or force coloured output.

ze config

Configuration management. Editing, validation, formatting, history, migration, dependency analysis.

ze config edit [file]
ze config import <file>...
ze config rename <old> <new>
ze config ls [prefix]
ze config cat <key>

ze config validate <file>
ze config dump <file>
ze config diff <f1> <f2>
ze config diff <N> <file>          # Diff against rollback revision N
ze config fmt <file>
ze config history <file>
ze config rollback <N> <file>
ze config graph <file>             # Config dependency analysis

ze config migrate <file>
ze config migrate --dry-run <file>
ze config migrate --list

ze config validate exits 0 for valid, 1 for invalid, 2 for file not found. The -q flag prints nothing (exit code only). The --json flag returns structured output. ze config fmt --check exits 1 if reformatting is needed and is the right thing for CI.

ze signal

Send commands to the running daemon over SSH.

Command	Effect
ze signal reload	Reload the configuration.
ze signal stop	Graceful shutdown without the GR marker.
ze signal restart	Graceful restart with the GR marker.
ze signal status	Dump daemon status.
ze signal quit	Goroutine dump and exit.

Exit codes: 0 ok, 1 not running, 2 no SSH credentials (run ze init), 4 signal delivery failed.

The Unix signals do the same: SIGHUP reloads, SIGTERM and SIGINT shut down gracefully, SIGUSR1 dumps status to stderr.

ze status

ze status

Exits 0 if the daemon is running, 1 if it is not. Suitable for systemd watchdog and load-balancer TCP probes.

ze cli and ze show

ze cli                     # Interactive shell
ze cli -c "peer list"      # One-shot command, exits after
ze show peer list          # Read-only query, safe in scripts

The interactive shell lives in Interfaces: CLI. The day-2 operator quick reference for ze show lives in Operation: show commands.

Runtime commands (inside the shell)

Inside ze cli or after ze cli -c "...", the command grammar is the same. The most-used groups:

Group	Command examples
Peers	peer list, peer * show, peer <sel> teardown <code>, peer <sel> capabilities, peer <sel> statistics, peer <sel> pause, peer <sel> resume, peer <sel> clear soft, peer <sel> borr <family>, peer <sel> eorr <family>, peer <sel> raw [<type>] <encoding> <data>, peer <sel> flush, set bgp peer <name> with <config>, set bgp peer <name> save, del bgp peer <name>, bgp summary
Interfaces	show interface, show interface brief, show interface <name>, show interface <name> counters
Connectivity tests	resolve ping <target>, resolve ping --source <addr> --count <N> --size <bytes> <target>, resolve traceroute <target>, resolve traceroute --source <addr> <target>
Routes	peer <sel> update text <attrs> nlri <family> <op> <prefix>, peer <sel> update hex <hex>, rib routes [scope] [filters...], rib show best [filters...] [terminal], rib show best status, rib clear in <selector>, rib clear out <selector> [family], rib inject <peer> <family> <prefix>, rib withdraw <peer> <family> <prefix>
Cache	cache list, cache forward <id> <peer>, cache release <id>
Commit windows	commit start <name>, commit end <name>, commit eor <name>, commit rollback <name>, commit show <name>, commit list
RPKI	rpki status, rpki cache, rpki roa, rpki summary
Metrics	bgp metrics values, bgp metrics list
Events	subscribe <namespace> event <type> [direction received|sent|both], unsubscribe <namespace> event <type> [direction received|sent|both]
Monitor	bgp monitor, bgp monitor peer <addr> event <type> direction <dir>
System	show system conntrack, show system update, show system sockets, show system kernel-log, show system goroutines, show system file-descriptors, show system profile cpu/heap, show runtime memory (Go allocator), show system memory (OS process), show health, show crashes, show debug
Class of Service	show class-of-service
IRR Filters	show bgp irr, show bgp irr prefix <peer>, show bgp irr check <peer> <prefix>, update bgp irr all, update bgp irr asn <asn>, update bgp irr as-set <as-set>
Diagnostics	show tcp-check <ip> <port>, show traceroute <target>, show capture interface <iface>, show dns lookup/cache
Live monitoring	monitor ping <target>, monitor traceroute <target>, monitor system netlink, monitor interface rate
IPsec	show vpn ipsec status, show vpn ipsec sa, clear vpn ipsec sa
PKI	show pki certificates
DNS cache	show dns cache list/stats/record, clear dns cache
Firmware	update system firmware {check,download,apply,restart,rollback}
Config archive	request config archive [<name>] (snapshot the running config to the store; optional name, defaults to a timestamp)
Announcements	announce flowspec <match> (rate-limit <bps> | discard) [tag <k> <v>] [for <dur>] (also announce unicast, announce blackhole), withdraw tag <k> <v>, withdraw id <N>, withdraw all, show announcements
Static routes	show static, show static summary
Policy routes	show policy routes
OSPF	show ospf, show ospf neighbor, show ospf interface, show ospf database [router|network|summary|asbr-summary|external|nssa-external], show ospf route, show ospf spf, show ospf border-routers, clear ospf process, clear ospf neighbor, clear ospf counters
IS-IS	show isis neighbor, show isis database [detail], show isis route [ipv6], show isis interface, show isis hostname, show isis spf-log, clear isis adjacency, clear isis counters
RSVP-TE	show rsvp-te lsp, show rsvp-te session, show rsvp-te interface, show rsvp-te fast-reroute
Firewall IRR	show firewall irr, show firewall irr prefix <asn-or-as-set>, update firewall irr all, update firewall irr asn <asn>, update firewall irr as-set <as-set>
BMP	show bmp sessions, show bmp peers, show bmp collectors, show bmp rib
Route reflection	show rr status, show rr peers
RPF	show bgp rib rpf <family> <source-addr> (reverse-path forwarding LPM lookup on sharded Loc-RIB; CIDR families only)
Daemon	daemon shutdown, route-refresh <family>, show uptime, show version, who, help, command-list, command-help <name>

The peer selector takes *, an exact IP, a peer name, an ASN (as65001), an IP exclusion (!addr), or a comma-separated list.

Pipes

Pipe	Effect
| json	Render the structured response as JSON.
| table	Render as a table.
| match <regex>	Drop rows that do not match.
| count	Just the row count.
| no-more	Disable paging on long output.
| log	Scrollback output for streaming commands.
| first N	Keep only the first N items. Server-side early termination when supported.
| last N	Keep only the last N items (trailing window).
| origin	Annotate IPs with ASN names (Team Cymru).
| resolve	Annotate IPs with reverse DNS hostnames.

ze bgp

Offline BGP protocol tools. No daemon required.

ze bgp decode <hex>              # Decode a BGP message hex to JSON
ze bgp encode <route-command>    # Encode a route command to BGP hex
ze bgp plugin cli                # Plugin debug shell

The same operations are available through the verb dispatcher: ze show bgp decode, ze show bgp encode.

ze exabgp

ExaBGP compatibility tools.

ze exabgp plugin <cmd> [args]    # Run an ExaBGP plugin under Ze
ze exabgp migrate <file>         # Convert an ExaBGP config
ze exabgp migrate --env <file>   # Convert an ExaBGP env file

ze interface

OS network interface management. Most commands run locally; ze interface migrate is dispatched to the running daemon.

ze show interface
ze show interface <name>
ze interface create dummy <name>
ze interface create veth <a> <b>
ze interface delete <name>
ze interface unit add <name> <id> [vlan-id <vid>]
ze interface unit del <name> <id>
ze interface addr add <name> unit <id> <cidr>
ze interface addr del <name> unit <id> <cidr>
ze interface migrate --from <iface>.<unit> --to <iface>.<unit> --address <cidr>

ze schema

Schema discovery.

ze schema list                   # List registered schemas
ze schema show <module>          # Show a YANG module
ze schema handlers               # Handler-to-module mapping
ze schema methods [module]       # RPCs from YANG

ze data

Manage ZeFS blob stores.

ze data [--path <store>] import <file>...   # Import files into the blob store
ze data [--path <store>] rm <key>...        # Remove entries from the blob store
ze data [--path <store>] ls [prefix]        # List entries in the blob store
ze data [--path <store>] cat <key>          # Print entry content to stdout
ze data [--path <store>] registered [key]   # List registered key patterns (or show one)

Flag	Purpose
--path <store>	Path to the blob store (default: {configDir}/database.zefs).

ze resolve

Resolution and connectivity tools: DNS, Team Cymru, PeeringDB, IRR, ICMP ping, and traceroute.

ze resolve dns [--server <host>] <op> <name>         # DNS queries (a, aaaa, txt, ptr)
ze resolve dns [--dnssec <mode>] <op> <name>         # DNSSEC validation: off (default), permissive, strict
ze resolve cymru [--dns-server <host>] asn-name <asn> # Team Cymru ASN-to-name
ze resolve peeringdb [--url <url>] max-prefix <asn>  # PeeringDB IPv4/IPv6 prefix counts
ze resolve peeringdb [--url <url>] as-set <asn>      # PeeringDB registered AS-SET names
ze resolve irr [--server <host>] as-set <name>       # IRR AS-SET expansion to member ASNs
ze resolve irr [--server <host>] prefix <name>       # IRR prefix lookup for AS-SET

ze resolve ping [--source <addr>] [--count <N>] [--size <bytes>] <target>
ze resolve traceroute [--source <addr>] <target>

ping and traceroute use an internal ICMP engine (no OS shell-out). ping has a 15-second timeout, traceroute has a 30-second timeout. Both use context-based cancellation so they cannot stall the dispatcher indefinitely. YANG tab-completion suggests the known local interfaces for --source.

Flag	Subcommand	Purpose
--server <host>	dns	DNS server (default: system DNS).
--dnssec <mode>	dns	DNSSEC validation of upstream answers: off (default), permissive (log a bogus chain, still answer), strict (reject a bogus chain).
--dns-server <host>	cymru	DNS server for TXT queries (default: system DNS).
--url <url>	peeringdb	PeeringDB API base URL (default: https://www.peeringdb.com).
--server <host>	irr	IRR whois server (default: whois.radb.net:43).
--source <addr>	ping, traceroute	Bind to a specific local address.
--count <N>	ping	Number of probes.
--size <bytes>	ping	Payload size.

ze completion

Generate shell completion scripts.

ze completion bash      # Bash completion script
ze completion zsh       # Zsh completion script
ze completion fish      # Fish completion script
ze completion nushell   # Nushell completion script (alias: nu)

Typical installation:

eval "$(ze completion bash)"
ze completion zsh > ~/.zsh/completions/_ze
ze completion fish > ~/.config/fish/completions/ze.fish

ze yang

YANG tree visualization and documentation.

ze yang tree [--json] [--commands] [--config]    # Print unified config + command tree
ze yang completion [--json] [--min-prefix N]     # Detect prefix collisions in trees
ze yang doc --list                               # List all commands
ze yang doc "<command>"                          # Show documentation for a command

Flag	Subcommand	Purpose
--json	tree, completion	Output as JSON.
--commands	tree	Show command nodes only (mutually exclusive with --config).
--config	tree	Show config nodes only (mutually exclusive with --commands).
--min-prefix N	completion	Minimum disambiguation depth to report (1--10).
--list	doc	List all commands.

ze plugin

Plugin execution and testing.

ze plugin <name> [args]                                  # Run a registered plugin's CLI handler
ze plugin test --plugin <name> --schema <config-file>    # Test plugin YANG schema and config delivery
ze plugin test --plugin <name> --tree <config-file>      # Show plugin config tree
ze plugin test --plugin <name> --json <config-file>      # Show plugin config as JSON

Registered plugins are listed dynamically; the set depends on the plugins compiled into the binary. The test subcommand is a debugging tool for plugin authors.

ze debug

Granular debug is edited as persistent state in debug.zefs using the same verb-first grammar as any other setting: set to enable, delete to disable, show to inspect, clear to reset. This matches VyOS syslog-level configuration, and replaces the earlier one-off toggle command.

ze set debug module <name>                          # Enable debug for a subsystem
ze set debug module <name> level <level>            # Set level (debug/info/warn/error)
ze set debug module <name> flag <flag>              # Add a debug flag
ze set debug module <name> scope <kind> <value>     # Add a scope filter (e.g. scope direction receive)
ze delete debug module <name>                       # Disable debug for a subsystem
ze delete debug module <name> flag <flag>           # Remove a flag
ze delete debug module <name> scope <kind> <value>  # Remove a scope filter
ze show debug profile                               # List stored profiles
ze show debug profile name <name>                   # Show a stored profile (offline)
ze set debug profile name <name>                    # Save current state as a named profile
ze set debug active name <name>                     # Load and apply a named profile
ze delete debug profile name <name>                 # Delete a named profile
ze clear debug                                      # Clear the default profile
ze set debug timeout <duration>                     # Auto-disable timer (e.g. 30m, 1h, 90s; 0=off)

Hierarchical prefixes work: ze set debug module bgp covers all bgp.* subsystems. Each plugin declares its valid flags via the debug YANG registry; invalid flags are rejected. Profiles are not auto-applied on reboot (safety); use ze set debug active name <name> after a restart.

show debug profile name <name> reads a stored profile (offline). To see the daemon's actual live state, use show debug inside the CLI (a YANG-dispatched RPC that needs a running daemon).

ze pipe

Offline pipe formatting. Reads JSON from stdin and applies the same pipe operators available inside the CLI, without a running daemon. (Formerly ze format.)

<command> | ze pipe json [compact]     # Format as JSON (pretty or compact)
<command> | ze pipe yaml               # YAML output
<command> | ze pipe table              # Box-drawing table
<command> | ze pipe text               # Space-aligned columns
<command> | ze pipe ndjson             # One compact JSON object per line
<command> | ze pipe match <pattern>    # Grep lines (case-insensitive)
<command> | ze pipe count              # Count items (JSON-aware)
<command> | ze pipe first <n>          # Take first N items
<command> | ze pipe last <n>           # Take last N items
<command> | ze pipe resolve            # Add reverse DNS for IP values

ze validate

Post-verify configuration validation check.

make ze-validate                          # Run after ze-verify

show host

Hardware inventory and tuning. Available as show host inside the CLI, or ze show host from the shell. Like show crashes, it is served by the daemon when it is running and falls back to the same in-process detection when it is not, so it works whether or not the daemon is up.

ze show host                     # Full hardware inventory (JSON)
ze show host cpu                 # CPU details
ze show host nic                 # Network interface hardware
ze show host memory              # DIMM layout, ECC status
ze show host dmi                 # DMI/SMBIOS data
ze show host thermal             # Temperature sensors
ze show host storage             # Disk, SMART health
ze show host kernel              # Kernel version, modules
ze show host all                 # Everything

ze appliance

Appliance fleet management (see appliance for details).

ze appliance init <name>
ze appliance build <name>
ze appliance run <name>
ze appliance push <name>
ze appliance config-push <name>
ze appliance config-push --all --parallel <N>
ze appliance list
ze appliance show <name>
ze appliance export <name>
ze appliance import <archive>

ze update-serve

Firmware update manifest and binary hosting for build infrastructure.

ze update-serve --manifest manifest.json --binary ze-appliance.bin --port 8090

Serves the manifest at /manifest.json and the binary at /ze.bin. Validates the requesting architecture via the X-Ze-Arch header.

ze l2tp

L2TP offline tools and daemon commands.

ze l2tp show ...                 # Forward to daemon (same as show l2tp)
ze l2tp clear ...                # Forward to daemon (same as clear l2tp)
ze l2tp decode --pretty          # Offline L2TP wire decode (stdin hex)

Inside the shell, request l2tp outgoing-call remote <name> called <number> places an LNS-side outgoing call toward a configured remote (which must have outgoing-calls enabled). It sends an OCRQ and blocks until the session establishes or the call fails.

ze help, ze env, ze show warnings, ze show errors

The introspection surface for AI assistants and operator scripts.

ze help --ai > ze-commands.json  # Machine-readable command catalogue
ze help command                  # Self-documenting command catalog
ze help command --json           # Machine-readable command catalog (JSON)
ze env list                      # All registered env vars
ze env list -v                   # Include current values
ze env get ze.log
ze show warnings                 # Active warnings (state-based)
ze show errors                   # Recent errors (event-based)

Both show warnings and show errors query the in-process report bus. The login banner reads from the same source.

ze doctor

System readiness checks. Run before starting the daemon.

ze doctor                        # Human-readable output
ze doctor --json                 # Machine-readable with diagnostic codes
ze doctor --json config.conf     # Check against a specific config
ze explain <code>                # Remediation guidance for a diagnostic code

Exit code 0 means ready; exit code 1 means at least one error-severity issue. See Health Checks for the full check list.

ze install

Zero-touch provisioning.

ze install serve \
  --interface eth0 \
  --network 192.168.1.0/24 \
  --image /path/to/gokrazy.img \
  --ssh-username admin \
  --ssh-password changeme

Starts DHCP (with PXE extensions), TFTP, and HTTP image servers. See Zero-Touch Provisioning.

Diagnostics and monitoring commands (runtime)

These commands run inside the CLI shell or via ze cli -c "...".

show health                      # Component health registry
show tcp-check <ip> <port>       # TCP connectivity probe
show traceroute <target>         # ICMP path trace
show capture interface <iface> tcp port <N> count <N> format text
show system sockets tcp          # Socket state (replaces ss)
show system kernel-log level warning count 50
show system goroutines summary   # Goroutine dump
show system file-descriptors summary
show system profile cpu duration 10s
show system profile heap
show runtime memory              # Go allocator: alloc, heap, GC (runtime.MemStats)
show system memory               # OS process memory (VmRSS/VmSize) from /proc/self/status
show crashes                     # Panic crash reports

show ping <target>                       # Bounded batch (5 probes, 5s timeout), prints a summary
show ping <target> count 10 timeout 3s   # count 1-100, timeout 1s-30s
show ping <target> size 1400             # ICMP payload bytes (1-65507), not total packet
monitor ping <target>                    # Continuous ICMP with live stats, until Ctrl-C
monitor ping <target> interval 500ms     # send cadence 100ms-30s
monitor ping <target> count 5 size 1400  # stop after 5 probes carrying a 1400-byte payload
monitor traceroute <target>      # mtr-style continuous traceroute
monitor system netlink all       # Kernel event stream (replaces ip monitor)
monitor interface rate           # Live interface rate tracking

show ping and monitor ping take the same count (1-100) and size (1-65507) keyword arguments; monitor ping additionally takes interval. size is the ICMP payload length (so size 1400 is 1400 payload bytes plus the 8-byte ICMP and 20-byte IPv4 headers), which differs from ping(8) counting the whole ICMP message. show ping runs a bounded batch and prints a summary; monitor ping streams live statistics, and omitting count streams until Ctrl-C.

DNS cache management (runtime)

show dns lookup <hostname> type A
show dns cache list              # All cached entries with TTL
show dns cache stats             # Hit/miss statistics
show dns cache record <hostname> # Specific cached name
clear dns cache                  # Flush all entries and reset all counters
clear dns cache stats            # Zero counters without removing entries
clear dns cache record <name>    # Delete all entries matching a name (all types)
clear dns cache record <name> type <type>  # Delete a single entry by name and type

Inspect and clear are split into separate per-action commands: show dns cache stats|list|record for inspection, clear dns cache, clear dns cache stats, and clear dns cache record for removal.

Traffic, anomaly, and DDoS visibility (runtime)

All read-only, safe in scripts. The show traffic feature, show anomaly detect, and show anomaly shape views report facts and status only; they do not act.

show traffic stat                # Aggregated snapshot: per-interface rates, top talkers, top ports, protocol mix
show traffic stat name <iface>   # One interface by name
monitor traffic stat             # Full-screen live traffic monitor (Esc/q to quit)
show traffic usage               # Per-interface eBPF byte accounting (traffic-usage plugin)
show traffic usage name <iface>  # One interface by name
show traffic feature             # Neutral per-source traffic feature signals (fan-out, ratios, entropy)
show traffic feature name <addr> # One source entity by address
show anomaly detect              # Recent behavioral anomaly incidents (report-only)
show anomaly shape               # Anomaly responder mode and armed sources
show ddos status                 # DDoS observation status (running, active attacks, ring size)
show ddos incidents              # Recent DDoS incident ring (newest first)
show ddos flowspec               # FlowSpec mitigation view (ddos-flowspec plugin)
show ddos local                  # Local mitigation view (ddos-local plugin)
show metrics pool                # Per-attribute-pool occupancy and dedup rates

The traffic, anomaly, and ddos command nodes are namespaces shared by their plugins: show traffic usage comes from traffic-usage, show anomaly detect from anomaly-detect and show anomaly shape from anomaly-shape, and show ddos status / show ddos incidents from ddos-observe while show ddos flowspec / show ddos local come from their own plugins.

Firmware update commands (runtime)

show system update               # Current update status
show system update history       # Last 20 update events

update system firmware check     # Trigger immediate version check
update system firmware download  # Download now (bypass spread, window)
update system firmware apply     # Full cycle: download+verify+stage+restart
update system firmware restart   # Restart into staged version
update system firmware rollback  # Restore previous version

See also

• Operation: show commands for the operator's day-2 cheat sheet.
• Interfaces: CLI for the long version of the interactive shell.
• Production Diagnostics for symptom-based troubleshooting.
• Health Checks for the health registry and ze doctor.
• In-tree command reference for the canonical, full version.

Adapted from main/docs/guide/command-reference.md.