Command reference

One page per command. Each opens with what the command is for, then a synopsis, then the prose a table cannot carry — how the interesting flags interact, and at least one worked example — and closes with the full flag table and the exit codes.

The synopsis, argument and flag tables on these pages are generated from the CLI itself by tools/gen_docs.py and checked by tests/test_docs.py, so a flag that exists is documented and a flag that is documented exists. The prose around them is written by hand.

Global options

These come before the subcommand, because they say which inventory the subcommand works on and how loudly it reports.

So the inventory is named once, for any command:

$ netviz -i examples/home-lab validate
no problems found

-v is repeatable and cumulative: one -v names the configuration file and the inventory root as they are found, two adds per-stage timings. --no-color is implied whenever stdout is not a terminal, and NO_COLOR in the environment forces it, so a transcript captured in CI carries no escape sequences.

--no-cache parses every file rather than reusing the parse cache, and remembers nothing for the next run. It is a global option because it is about the run rather than about one command; the cache is keyed by file contents and is safe to leave on. See netviz cache and docs/configuration.md.

-h/--help is not in the table because Click supplies it rather than netviz, but it works on the group and on every subcommand, and running netviz with no command at all prints the same help. Every command that reads an inventory reads the one -i names; init and import, which write one, take their target as an argument and as -o respectively.

Output discipline

Data on stdout, commentary on stderr. render writes the diagram to stdout when no --output is given, so its findings and progress notes go to stderr instead. That is what makes netviz render -f json | jq and netviz validate > report.txt both do what they look like they do. Colour is used only when the stream is a terminal.

One consequence worth knowing when reading the transcripts in these pages: the checker that executes them captures stdout and stderr separately and prints stdout first, so a block that mixes the two shows them grouped rather than interleaved the way a terminal would.

Environment variables

auto takes PyYAML's libyaml bindings when the installed wheel carries them — several times faster on a large inventory — and falls back to the pure-Python parser otherwise. The two accept exactly the same documents and report the same line and column for a problem; they differ only in PyYAML's own wording for a syntax error. Set python to pin the slow path, or libyaml to refuse to start without the fast one.

NETVIZ_HYPOTHESIS_PROFILE affects the test suite rather than the tool; see docs/testing.md.

Exit codes

Every command draws its codes from the same table; each page narrows it to the codes that command can actually return.

See also

• docs/README.md — the documentation index.
• docs/getting-started.md — the tutorial these commands appear in.
• docs/configuration.md — netviz.toml, so most of these flags need typing only once.
• docs/architecture.md — what happens between the command line and the output.