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.

ze

Start the daemon or dispatch to a subcommand.

ze <config-file>           # Start the daemon with a config file
ze start                   # Start from the database

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.

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 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>
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.

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 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 wraps the host ICMP ping and has a 15-second timeout. traceroute wraps the host traceroute (UDP or ICMP, depending on the underlying tool) and 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).
--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 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 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.

See also

• Operation: show commands for the operator's day-2 cheat sheet.
• Interfaces: CLI for the long version of the interactive shell.
• In-tree command reference for the canonical, full version.

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