introspection

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

Ze is self-documenting. Every plugin, every environment variable, every RPC, every event type, and every CLI command is registered at startup and discoverable at runtime. Nothing exists unregistered: the system enforces this with compile-time init() registration and a runtime abort on unregistered access. The result is that the binary describes itself, and the description does not go out of sync with the code because it is generated from the code.

This is the surface that makes Ze genuinely AI-first, and it is also the one that saves human operators from reading stale man pages.

The CLI is the API

The design principle is short. Every command available through ze cli (interactive or ze cli -c) is exposed programmatically through the MCP ze_execute tool. The REST API reaches the same handlers through the web server, and the Looking Glass reaches the read-only subset of them. There is no separate "API surface". The CLI and the programmatic surface are the same thing.

This means no command is CLI-only or API-only. There is no translation layer between a human and a machine interface. Any new CLI command is automatically available to AI assistants and to HTTP clients the moment the registration lands in the binary.

Generating the machine-readable reference

ze help --ai > ze-commands.json

ze help --ai generates a machine-readable command reference from the live binary. The output is assembled from the plugin registry, the YANG schemas, and the RPC registrations. It cannot go stale because it is generated from the code, not written by hand. Feed the file to an AI assistant as context and the assistant can pick the right command without trial and error.

Runtime introspection commands

The full introspection surface is a set of ze schema and ze env subcommands, plus ze --plugins and ze help --ai.

Command	What it shows
ze schema list	Every registered YANG module.
ze schema show <module>	The full YANG content of a module.
ze schema methods [module]	Every RPC, with its parameters, parsed out of the YANG.
ze schema events	Every notification and event type defined in the YANG.
ze schema handlers	Which handler serves which YANG module.
ze schema protocol	Protocol version and wire format info.
ze env list	Every registered environment variable with its type and default.
ze env list -v	The same, plus the current value of each.
ze env get <key>	Full details of one environment variable.
ze --plugins	Every plugin compiled into this binary, with its families, capabilities, and dependencies.
ze help --ai	The machine-readable command reference.

Inside a running ze cli, the same information is available through command-list and command-help <name>.

Build-time verification

The same registration machinery powers a set of Make targets that keep the documentation and the code honest.

Target	What it does
make ze-inventory	Full project inventory: plugins, YANG modules, RPCs, families, tests, packages.
make ze-inventory-json	The same, in machine-readable JSON.
make ze-command-list	Every CLI command with its wire method, help text, read-only flag, and source location.
make ze-validate-commands	Cross-check the YANG command tree against the registered handlers.
make ze-doc-drift	Detect documentation that has drifted from the code.

make ze-doc-drift is the one that pays for itself. It catches every case where the in-tree documentation says a flag exists that no longer exists, a command takes a parameter it no longer takes, or a plugin has a family that has moved.

How the registration works

The self-documenting property emerges from one design rule: nothing exists unregistered.

Plugins register via registry.Register() in init(), declaring their name, families, capabilities, YANG schema, dependencies, event types, send types, and features. Environment variables register via env.MustRegister(), and calling env.Get() with an unregistered key aborts the process. RPCs are defined in YANG, so no command handler exists without a schema definition. CLI dispatch is auto-generated from the registrations, with no hand-wired dispatch tables. Tab completion is driven by the same schemas, so new config leaves appear automatically. The web UI forms are generated from the YANG, so new fields appear there too.

Add a plugin with a YANG schema and the CLI, the web UI, tab completion, schema discovery, the inventory, and the environment variable listing all update at once. No manual wiring.

Why this matters

Most network daemons add an API endpoint and hope someone wraps it for the use case in front of them. Ze exposes its entire command surface through a self-describing interface that an AI assistant or a script can discover and use without external documentation. ze help --ai is generated from code. The MCP tools have typed parameters. The command list is queryable at runtime.

No other open-source network daemon is built this way.

See also

• MCP for the AI-facing transport that consumes this surface.
• REST API for the HTTP surface.
• Command reference for the long list.

Adapted from main/docs/features/introspection.md and main/docs/features/ai-first.md.