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 debug show | ze pipe match reactor    # Offline pipe formatting
ze start --web-only                 # Start daemon with web UI only (no SSH CLI)

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. ze pipe (formerly ze format) brings the YANG pipe operators (json, table, match, count, resolve, origin, first, last) to any command's output offline: pipe through ze pipe json or ze pipe match <pattern>. ze start --web-only starts the daemon with the web UI but without the SSH CLI server.

Every command that takes a filename argument treats - as stdin (reading) or stdout (writing), so configs stream through pipes without temp files: generate | ze config show -, ze config migrate -o - old.conf. stdin is consumed once (a second - in one command fails cleanly), a file literally named - is ./-, and the TTY-bound editor commands (ze config edit, ze config rollback, ze config history) reject it.

Verb-first grammar

Operational commands read verb first: the action comes first, then the object, then any filters. Queries start with show, live streams with monitor, and runtime actions with request (or a dedicated action verb such as announce, withdraw, clear, set, delete, update, route-refresh).

show host                                   # read-only query
show crashes                                # read-only query
show event list                             # read-only query
show metrics pool                           # read-only query
monitor traffic stat                        # live stream
request config archive backup-2026          # runtime action
request l2tp outgoing-call remote lns1 called 5551234
announce flowspec destination 192.0.2.0/24 discard

After the verb comes the object, which is the component or plugin that owns the command (host, crashes, ddos, anomaly, traffic, l2tp, and so on), so the command tree mirrors the plugin tree. After the object come positional keyword filters. Address family and other qualifiers are keywords in the grammar (show neighbor ipv6, show traffic usage name eth0), never --flags. The --flag spelling belongs only to the offline ze ... shell tooling, not to the command model.

The grammar is now uniform: the last noun-first reads were nested under show (event list became show event list, command list/help/complete became show command ...), enabling debug for a subsystem became set debug module <name> and disabling it delete debug module <name>, and clear interface counters [<name>] puts the action ahead of the interface name.

Hyphen names one thing; a space opens a namespace. A hyphen inside a token joins words that name a single indivisible thing, so graceful-restart, as-set, max-prefix, and show class-of-service keep their hyphens. When the left part is an object with members, it becomes its own token so completion can enumerate the members and the command tree keeps mirroring the plugin tree. Several commands moved to this namespace form: show traffic stat (was show traffic-stat), show traffic feature, monitor traffic stat, show bgp health (was show bgp-health), show flow export / show flow recent, show policy routes, show runtime memory (Go allocator) and show system memory (OS process, was show system memory-map), ze pipe (was ze format), and ze isis decode (was ze isis-decode). If you have muscle memory for the old hyphenated spellings, retype them with a space.

Interactive launcher (no arguments)

Run ze with no arguments in an interactive terminal and it opens a hierarchical, navigable menu of every command instead of printing static help. The launcher groups commands by section, lets you drill into subcommands, and returns the command you select so you can run it.

ze                                  # Interactive command menu (TTY only)

Behaviour	Detail
TTY detection	The menu opens only when stdin is a terminal. When piped or scripted, ze prints static help and exits with status 1.
Grouping	Commands are listed under section headers. The Operations section also folds in YANG-dispatched verbs, sorted alphabetically.
Drill-down	Entries with subcommands show a > arrow; selecting one descends a level. A breadcrumb at the top shows where you are.
Type-to-filter	Typing narrows the visible entries by name prefix. The filter is shown at the bottom.
Keys	Up/Down navigate, Enter selects (or descends), Left/Backspace go back a level, Esc clears the filter then quits.

The launcher renders in an alternate screen and uses the semantic color system below (structure magenta for the ze title and section headers, identity cyan for command names, blue for the breadcrumb, gray for descriptions and hints).

Color system

Every terminal surface (the launcher, help output, autocomplete, the config editor, the BGP dashboard, ping and traceroute monitors, and structured logs) shares one semantic palette. The rule is consistency: the same color always means the same thing, so you read meaning, not decoration. Hierarchy comes from weight (normal, dim, bold), not hue.

There are seven foreground roles, the practical ceiling before colors stop carrying meaning. The palette is dark-terminal-first and uses ANSI 256-color codes (not true-color) for maximum compatibility, including SSH sessions over constrained links. It degrades automatically: 16-color terminals get the base ANSI mapping, monochrome terminals get bold and dim only.

Role	Meaning	Color	Used for
structure	"what kind of thing am I looking at?"	205 magenta	Headers, section titles, prompt path, mode indicators
identity	"what can I type or act on?"	73 cyan	Commands, keywords, completion entries
value	"what is the system telling me?"	82 green	Data values, counts, addresses, ASNs, route counts
caution	"something is off, not broken"	214 orange	Warnings, flags, non-default or degraded state
danger	"something is broken, act now"	196 red	Errors, down state, validation failures
muted	"background info, skip on fast scan"	241 gray	Descriptions, secondary text, timestamps, hints
context	"where am I?"	33 blue	Navigation breadcrumb, current path, positional info

Two modifiers layer on top of a role rather than acting as roles: bold for emphasis (selected row, active state) and a paired dark background for inline validation and selected-row highlight.

SSH sessions render the same TUI as local sessions. The Wish middleware detects terminal capabilities per connection and the 256-color codes degrade automatically, so no separate palette is needed.

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>
show bgp rib rpf <family> <source-addr>   # reverse-path LPM lookup in the Loc-RIB (CIDR families)

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.

In edit mode, show | compare diffs the candidate against the committed config and prints only the parts that differ, not the whole tree with a few changed lines buried in it, so a large config still shows a small, readable change set before you commit.

Host, diagnostics, RPKI, monitor, daemon

show host [cpu|nic|memory|dmi|thermal|storage|kernel|platform|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 vpn ipsec status              # IPsec tunnel status
show vpn 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 runtime memory             # Go allocator: alloc, heap, GC (runtime.MemStats)
show system memory              # OS process memory (VmRSS/VmSize) from /proc/self/status
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
show debug                      # Live debug module state (YANG-dispatched)
show class-of-service           # CoS profiles and assignments
show bgp irr                    # IRR filter status per ASN
show traffic stat               # Aggregated traffic snapshot (top talkers, ports)
show traffic usage              # Per-interface eBPF byte accounting
show traffic feature            # Neutral per-source traffic signals (facts, not verdicts)
show anomaly detect             # Behavioral anomaly incidents (report-only)
show anomaly shape              # Anomaly responder mode and armed sources
show ddos status                # DDoS observation status
show ddos incidents             # Recent DDoS incident ring (newest first)
show metrics pool               # Per-attribute-pool occupancy and dedup rates
monitor ping <target>           # Continuous ping with live stats (count, size, interval)
monitor traceroute <target>     # mtr-style continuous traceroute
monitor system netlink all      # Kernel route/link/address changes
monitor interface rate          # Live interface rate tracking
monitor traffic stat            # Full-screen live traffic monitor
bgp monitor                     # Live event stream (see Monitoring)
bgp monitor peer <addr> event update direction received
daemon shutdown
route-refresh <family>
help
help command                    # Self-documenting command catalog
help command --json             # Machine-readable catalog
command-list
command-help <name>

show host and show crashes are served by the daemon when it is running and fall back to the same in-process detection when it is not, so both work whether or not the daemon is up. That matters most for show crashes: you inspect a crash exactly when the process has died. The traffic-visibility verbs (show traffic stat, show traffic usage, show traffic feature), the report-only show anomaly detect and show anomaly shape, and show ddos status / show ddos incidents are all read-only and safe in scripts.

On-demand route origination uses its own verbs: announce flowspec <match> (rate-limit <bps> | discard) [tag <k> <v>] [for <dur>] originates a tracked FlowSpec rule (with siblings announce unicast and announce blackhole), withdraw removes announcements by tag, id, or all, and show announcements lists the active set.

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).
| first N	Keep only the first N items. Server-side early termination when supported by the command.
| last N	Keep only the last N items (trailing window).
| 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. Plugin-provided commands are included too: the interactive completer asks the running daemon for the live plugin command set per request, so a command a plugin registers appears in tab-completion, not just when typed blind. (Offline shell completion from ze completion bash|zsh|fish|nushell stays YANG-only, since it runs without a daemon.) 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, main/docs/guide/operations.md, main/docs/guide/command-reference.md, and main/docs/architecture/cli/color-system.md.