cli

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

The CLI is a network OS shell, not a Unix wrapper. You connect over SSH, you get tab completion driven by the YANG schema, and the workflow is the one operators of JunOS or Cisco IOS already know: edit, diff, commit, rollback. This is the long version of the CLI tour.

The four entry points

ze cli                              # Interactive shell
ze cli -c "peer list"               # One-shot command, exits after
ze show peer upstream detail        # Read-only query, safe in scripts
ze start --cli                      # Start daemon + interactive CLI attached

ze cli is the interactive path. ze cli -c runs a single command and exits, with a non-zero exit code on error so it composes with shell pipelines. ze show is the read-only subset: it cannot mutate state, which is exactly what you want in a monitoring script. ze start --cli starts the daemon and immediately drops into an interactive CLI session attached to it.

A handful of ze show subcommands run locally without touching the daemon at all (version, bgp decode, bgp encode, env, schema, yang, data (ls, cat, registered), config (dump, diff, history, ls, cat, fmt), interface). The rest go through the SSH server built into the Ze process.

Connecting

The SSH server is part of the daemon. ze init walks you through username, password, host, and port the first time. Defaults are 127.0.0.1:2222 with an auto-generated ED25519 host key. Credentials live in the Ze database (database.zefs) with bcrypt-hashed passwords.

Override the host or port from the environment when you talk to a remote daemon:

export ZE_SSH_HOST=10.0.0.1
export ZE_SSH_PORT=2222
ze cli

Commands

The full list lives in reference/command-reference.md. The most-used groups are these.

Peer commands

peer list
peer * show
peer <selector> teardown <code>
peer <selector> capabilities
peer <selector> pause
peer <selector> resume
set bgp peer <name> with <config>
del bgp peer <name>
bgp summary

The peer selector takes * (all peers), an exact IP, a peer name, an ASN (as65001), an IP exclusion (!<IP>), or a comma-separated list of IPs.

Route and RIB commands

peer <sel> update text <attrs> nlri <family> <op> <prefix>
peer <sel> update hex <hex>
rib routes received [peer] [family]
rib routes sent     [peer] [family]
rib clear-in        [peer] [family]
rib clear-out       [peer] [family]
rib inject  <peer> <family> <prefix> [attrs...]
rib withdraw <peer> <family> <prefix>
rib rpf <family> <source-addr>

rib inject takes a peer label, not a live session, so you can prime the Adj-RIB-In without anyone connected.

Commit windows

The commit workflow lets you batch multiple route operations into one named transaction.

commit start <name>
commit end <name>
commit eor <name>
commit rollback <name>
commit show <name>
commit withdraw <name>
commit list

Config editor verbs

deactivate <path>               # Mark a node inactive (kept in file, skipped at apply)
activate <path>                 # Clear inactive flag
insert <path> before <ref>      # Insert into an ordered list
rename <old> <new>              # Rename a keyed list entry
copy <src> <dst>                # Copy a keyed list entry

deactivate and activate work on both containers and leaf nodes. An inactive node is kept in the config file but skipped at apply time.

Host, diagnostics, RPKI, monitor, daemon

show host [cpu|nic|memory|dmi|thermal|storage|kernel|all]
show health                     # Component health registry
show policy list                # BGP filter types and named instances
show policy chain <peer>        # Effective BGP filter chain for a peer
show policy-routes              # Policy-based routing rules (PBR)
show static                     # Static routes with BFD status
show interface rate             # Per-interface rate tracking
show bmp sessions               # BMP receiver sessions
show bmp peers                  # BMP monitored peers
show bmp collectors             # BMP sender collector status
show bmp rib                    # BMP monitored routes
show rr status                  # Route reflector running state
show rr peers                   # Route reflector peer states
show ipsec tunnels              # IPsec tunnel status
show ipsec sa                   # Active IKE and Child SA details
show pki certificates           # Loaded certificates with expiry
rpki status
rpki cache
rpki roa
rpki aspa                       # ASPA records and validation state
show dns lookup <name>          # DNS resolution
show dns cache list             # Cache entries with TTL
show dns cache stats            # Hit/miss statistics
clear dns cache                 # Flush the DNS cache
show system sockets             # TCP/UDP socket state (replaces ss)
show system kernel-log          # Kernel log (replaces dmesg)
show system goroutines          # Goroutine dump
show system file-descriptors    # FD counts and limits
show system profile cpu         # CPU pprof profile
show system profile heap        # Heap pprof profile
show system memory-map          # Process memory map
show tcp-check <ip> <port>      # TCP connectivity probe
show traceroute <target>        # ICMP path trace
show capture interface <iface>  # Live packet capture (replaces tcpdump)
show crashes                    # Panic crash reports
monitor ping <target>           # Continuous ping with live stats
monitor traceroute <target>     # mtr-style continuous traceroute
monitor system netlink all      # Kernel route/link/address changes
monitor interface rate          # Live interface rate tracking
bgp monitor                     # Live event stream (see Monitoring)
bgp monitor peer <addr> event update direction received
daemon shutdown
route-refresh <family>
help
command-list
command-help <name>

Pipes

The shell understands a small set of network OS pipe operators. They are not Unix 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 (monitor ping, monitor traceroute).
| origin	Annotate IP addresses with ASN names via Team Cymru. Useful with traceroute.
| resolve	Annotate IP addresses with reverse DNS hostnames.

| json is the one that matters most for scripting. The output is the same JSON envelope every other Ze surface produces, so you can pipe it through jq and get the same fields you would see from the REST API. Pipes compose: monitor traceroute <target> | log | origin adds one line per round with ASN annotations.

Default output format

The display format pipes (| text, | table, | json, | yaml, | ndjson) override the default for one command. You can change the default itself. The config sets it once for all sessions:

environment {
    cli {
        format {
            default text;        # text (default), table, json, yaml, or ndjson
        }
    }
}

A session override is set cli format <value> in operational mode; set cli format with no argument prints the current format. An explicit display pipe on a command always wins over the configured or session default, so show peer list | json is JSON regardless of the default.

Command-owned filters

Some pipe segments are owned by the command rather than the shell. show bgp rib | received, show bgp rib | advertised, and show bgp rib | peer <selector> are folded into server-side arguments so the daemon does the filtering and streams only the matching rows, instead of the shell filtering a full response after the fact. Display and transform pipes (json, table, resolve, origin, and so on) stay client-side. In interactive mode the whole pipe chain is validated up front against each command's declared filter metadata, so an unsupported or misspelled filter is rejected before the command runs rather than after it has already produced output.

Interactive features

In ze cli, tab completion works on every position: command verbs, peer names, address families, log levels. History is persisted across sessions. Ctrl-C cancels the current command, Ctrl-D exits. The prompt reflects your current edit context (ze[bgp peer upstream]#).

Operational command arguments are YANG-typed. The schema that drives completion also declares the type, range, and pattern of each argument, so the same validation that catches a bad value in the config editor catches a bad value typed at an operational command. A family argument that no peer has negotiated, or a port outside 1-65535, is rejected against the schema before the command is dispatched.

Show convention

Read-only queries follow the show <noun> ... convention with the selector after the noun: show peer detail <selector>, show peer capabilities <selector>, show summary, and show summary <afi>/<safi> for a per-family summary. The family argument on show summary is checked against the families peers have actually negotiated, and an unknown or un-negotiated family rejects with the set of families currently reachable on the running daemon.

Session transcript

Ze can record a local transcript of ze cli and ze config edit sessions, capturing both the commands you type and their output. Transcripts are written to $XDG_DATA_HOME/ze/transcripts/, which is useful for recovering what you did after a disconnect. Writes are best-effort and never block the CLI: if the transcript cannot be written, the session continues normally.

Enable it in config or via the environment:

environment {
    cli {
        transcript enabled;
    }
}

The equivalent environment variable is ze.cli.transcript.

Signals

ze signal is the SSH-based control surface for the daemon process itself, separate from the in-shell commands above.

Command	Effect
ze signal reload	Reload the on-disk config.
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.

The same actions are available as Unix signals: SIGHUP reloads, SIGTERM and SIGINT shut down gracefully, SIGUSR1 triggers a status callback logged at Warn level via the structured logger, SIGQUIT dumps goroutines (mapped to ze signal quit).

See also

• CLI tour for the five-minute version.
• Show commands for the operator's day-2 quick reference.
• Command reference for the long list.
• Web UI for the same operations through a browser.

Adapted from main/docs/guide/cli.md, main/docs/features/api-commands.md, and main/docs/guide/operations.md.