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 start                   # Start from the database
ze start <config-file>     # Start the daemon with a config file
ze -                       # Start the daemon with a config read from stdin

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.

Position 1 takes a command, not a path. A bare ze <config-file> is rejected: a config file named after a command (bgp, signal) would have been dispatched as that command and never loaded, so the free-form path moved behind the start keyword. - stays as a position-1 sentinel because it cannot collide with a command name.

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 start

Start the daemon. With no path it starts from the blob database, which requires ze init to have run. With a path it starts from that config file, falling back to filesystem storage when the path is not a blob key.

ze start                            # From the database
ze start /etc/ze/router.conf        # From a config file
ze start --cli                      # Start and attach an interactive CLI
ze start --web 3443                 # Start with the web UI on port 3443
ze start --web 3443 --insecure-web  # Web UI without auth, bound to localhost
ze start --web-only --web 3443      # Web UI only, no daemon (config editing)

Flag	Purpose
--cli	Attach an interactive CLI after startup.
--web <port>	Enable the web UI on the given port.
--web-only	Web UI only, no daemon. Cannot be combined with a config path.
--insecure-web	Disable web auth. Binds to localhost only.
--mcp <port>	Enable the MCP server on the given port.
--mcp-token <token>	Bearer token for MCP authentication.

Global flags such as -d go before the keyword: ze -d start router.conf.

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 set [options] <file> <path...> <value>
ze config activate [options] <file> <path...>
ze config deactivate [options] <file> <path...>

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 config set, ze config activate, and ze config deactivate edit a stored config without contacting the daemon. Pass --reload when you also want a running daemon told to re-read it:

ze config set router.conf bgp session asn local 65001            # Edit only
ze config set --reload router.conf bgp session asn local 65001   # Edit and reload

Options go before the positional arguments, so --reload follows the verb, not the value.

This is the opposite of the older behaviour, where these three notified by default and --no-reload opted out. --no-reload no longer exists and is rejected as an unknown flag (exit 2). ze config edit is unchanged: it still reloads when a daemon is reachable.

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 reboot	Graceful shutdown, then an OS reboot. Needs root on Linux.
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.

ze signal reload, ze signal status, and ze signal quit send the verb-first daemon commands request reload, show status, and request halt. The daemon reload, daemon status, and daemon quit spellings were removed; the dispatcher answers unknown command for each. ze signal stop, ze signal restart, and ze signal reboot send the bare words stop, restart, and reboot. Those three are the exception to the verb-first grammar: the SSH exec middleware answers them before the dispatcher, which registers no key for them.

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 "show bgp peer list"  # One-shot command, exits after
ze show bgp 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. Every command is verb-first: it starts with one of twelve canonical verbs, and the words after the verb are the YANG path.

Role	Verbs
Read	show, monitor, resolve
Config-tree mutation	set, delete
Runtime action	clear, request, commit, update, cache, create, debug

One operator surface is deliberately not verb-first: the text-bridge compatibility verbs announce, withdraw, peer, and help mirror a legacy line protocol whose grammar that protocol fixes. stop, restart, and reboot are also bare, because the SSH exec middleware answers them before the dispatcher.

Everything else is in the command tree under a verb. The old bare forms (bgp summary, daemon reload, rpki status, cache list, route-refresh, and the rest) are not, and the dispatcher answers unknown command for each. The most-used groups:

Group	Command examples
Peers	show bgp peer list, show bgp peer <sel> detail, show bgp peer <sel> capabilities, show bgp peer <sel> statistics, show bgp peer <sel> history, show bgp peer <sel> rib, show bgp summary [<afi>/<safi>], show bgp health, request peer <sel> teardown <code> [message], request peer <sel> pause, request peer <sel> resume, request peer <sel> flush, request peer <sel> clear soft, request peer <sel> refresh <family>, request peer <sel> borr <family>, request peer <sel> eorr <family>, peer <sel> raw [<type>] <encoding> <data>, delete bgp peer <sel>, update bgp peer <sel> prefix
Interfaces	show interface, show interface brief, show interface scan, show interface type <type>, show interface errors, show interface rate [<name>], show interface name <name> detail, show interface name <name> counters, clear interface counters [<name>]
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>, show bgp rib [received|sent|in|out] [filters...], show bgp rib best [filters...], show bgp rib best status, show bgp rib status, clear bgp rib in <selector>, clear bgp rib out <selector> [family], request bgp rib inject <peer> <family> <prefix> [attrs...], request bgp rib withdraw <peer> <family> <prefix>
Cache	show cache, request cache retain <id>, request cache release <id>, request cache expire <id>, request cache forward <id> <selector>
Commit windows	request commit start <name>, request commit end <name>, request commit eor <name>, request commit rollback <name>, request commit show <name>, request commit withdraw <name> route <prefix>, request commit list
RPKI	show bgp rpki status, show bgp rpki cache, show bgp rpki roa [<prefix>], show bgp rpki summary, show bgp rpki aspa, request bgp rpki validate <prefix> <origin-asn>
Metrics	show metrics values, show metrics list, show metrics name <name>, show metrics pool
Events	request subscribe <namespace> event <type> [direction received|sent|both], request unsubscribe <namespace> event <type> [direction received|sent|both]
Monitor	monitor bgp, monitor bgp peer <addr> event <type> direction <dir>, monitor event
System	show status, show system conntrack, show system platform, show system update, show system sockets, show system kernel-log, show system goroutines, show system file-descriptors, set system file-descriptors max <n>, 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, show vpn ipsec peer name <name>, show vpn ipsec dataplane sa [spi <spi>], show vpn ipsec dataplane policy, show vpn ipsec dataplane drift, clear vpn ipsec sa, monitor vpn ipsec
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
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] (every row carries own, true for an LSP this node originated), 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	request reload, request shutdown, request halt, request quiesce, request reboot, show status, show reload-status, show uptime, show version, who, help, show command list, show command help <name>

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

Peer-scoped destructive commands take one peer and refuse anything else. request peer <sel> teardown, pause, resume, flush, clear soft, peer <sel> raw, and delete bgp peer <sel> share one resolver. It accepts a name, an address, an ASN (as65001), or a prefix. It refuses * and an empty selector (the command needs one specific peer), every exclusion form (!edge1, !as65001, !10.0.0.0/24), and any selector that matches more than one peer. An exclusion names a set, so in a two-peer topology it would resolve to one peer and tear down the other, then start failing the day a third peer is configured. A selector that resolves to nothing is an error, not a silent success.

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-test replay

Replay a captured BGP session through the real read path with a deterministic clock. A capture is the bounded JSONL file a peer writes when bgp peer <name> capture enabled true is set, and it holds the bytes the peer sent, the malformed UPDATE included.

ze-test replay [--json] [--local-as N] [--peer-as N] [--router-id N] <capture-file|->

Flag	Purpose
--json	Emit the replay report as JSON.
--local-as <N>	Local AS override. 0 reads it from the capture header.
--peer-as <N>	Peer AS override. 0 reads it from the capture header.
--router-id <N>	Router-ID override. 0 reads it from the capture header.

The report gives the steps applied, the config operations replayed alongside them, the FSM states walked, what the session sent, and the dropped-event count. Exit code 2 is a usage error, 1 is a replay failure.

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                       # Every interface, full detail
ze show interface <name>                # One interface (served in-process)
ze show interface brief                 # One line per interface: name, state, IP, MTU
ze show interface scan                  # Discover and classify every OS interface
ze show interface type <type>           # Only interfaces of that type
ze show interface errors                # Only interfaces with a non-zero error or drop counter
ze show interface rate [<name>]         # Per-second rx/tx rates
ze show interface name <name> detail    # Full detail for one interface
ze show interface name <name> counters  # Counters for one interface
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>

The seven show interface keywords go to the daemon. Bare ze show interface and ze show interface <name> are served in-process, so they read the local kernel with no daemon. show interface detail <name> and show interface counters <name> were removed: the name is now selected with name <name> before the keyword. Inside the daemon grammar the create verb reads create interface veth name <name> <peer>.

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-repository-check                          # Run after ze-precommit-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 appliance kernel [options] [<name>]              # Download or build a Ze kernel
ze appliance kernel --target runtime --arch amd64   # installer (default) or runtime
ze appliance kernel --print-cache-dir               # Print the cache path and exit
ze appliance kernel --evict-cache                   # Bound the cache namespace and exit

ze appliance kernel flag	Purpose
--target <target>	installer (default, monolithic PXE Image) or runtime (modules plus vmlinuz tree for the gokrazy appliance).
--arch <arch>	amd64 or arm64. Default comes from the appliance config, then the host.
--profile <profile>	Kernel profile token. Default is the target default: qemu for installer, runtime for runtime.
--builder <backend>	docker or qemu. Default is docker when available.
--version <ver>	Linux kernel version.
--print-cache-dir	Print the durable cache path for this kernel and exit. Downloads nothing, builds nothing.
--evict-cache	Bound this kernel's cache namespace to the most recent entries and exit. Evicts, does not build.

These run on the build host. Build a host binary for them (bin/ze-setup, from cmd/ze with tags ze_core,ze_setup); never cross-compile the tool that drives the build.

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 help ai is the canonical spelling. ze help --ai still works as a hidden alias.

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.

Diagnostic codes added since the last sync, each with ze explain <code> guidance:

Code	Reports
doctor-config-root-unclaimed	A configured subtree that commits and reaches no plugin and no hub handler.
doctor-config-claims-unavailable	The claim set could not be read, so the check above cannot run.
doctor-tls-reference	An environment.web or DNS tls { certificate } name the PKI store does not hold.
doctor-bgp-capture-directory	The BGP capture directory is missing or not writable.
doctor-iface-ra-forwarding	An interface advertises Router Advertisements while net.ipv6.conf.<dev>.forwarding is 0.
doctor-vpp-lcp-plugin	vpp.lcp is on but the running VPP does not load linux_cp_plugin.so. A failed probe degrades to WARNING.

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.