netviz GitHub

netviz render

Draw the inventory once and write the result somewhere. render is the one-shot form of netviz's rendering pipeline: pick a layer, narrow or summarise the topology, and hand back a DOT file, an SVG, a self-contained HTML page, a PNG, a PDF, a Mermaid flowchart or the resolved graph as JSON.

Every concept behind the flags — what each layer shows, how the filters combine, what aggregation folds, what a theme is, what the JSON and HTML artefacts contain — lives in docs/rendering.md, because watch, web and path --highlight share it. This page is the reference for the command itself.

Synopsis

netviz [GLOBAL OPTIONS] render [OPTIONS]

Validation runs first

Validation always runs before the render, and errors refuse it: a diagram silently drawn from an inventory with a dangling cable is worse than no diagram.

Diagnostics go to stderr, always, because stdout may be the diagram itself. That is what makes netviz render -f svg > topology.svg safe.

See netviz validate for the checks and docs/validation.md for how they are graded.

Choosing a layer and a format

--layer picks the question the diagram answers: l1 (the default) for the physical topology, l2 for the same topology annotated with VLANs, l3 for the IP subnets and who is addressed in them, overlay for the tunnels and what runs inside what, routing for the BGP sessions and OSPF adjacencies clustered by VRF, physical for the cabling record with its patch panels, rack for a front elevation per rack, and power for the PDUs and the outlet and PoE feeds into everything they power. The table in Layers says what each one draws and when to reach for it.

rack is the one layer -f mermaid cannot draw, because an elevation is a grid and Mermaid has no way to express one. power is an ordinary topology of nodes and edges, so every format holds it.

-f/--format decides what the artefact is. svg, html, png and pdf need Graphviz on the PATH; dot, mermaid and json do not. The comparison table is in Output formats.

--layer is repeatable only for -f html, which draws each layer and puts a switcher over them. Every other format holds one layer, and asking for two is a usage error.

-o/--output writes to a file instead of stdout and creates parent directories on the way. It is required for png and pdf when stdout is a terminal — netviz will not spray a binary at your prompt.

Worked examples

A layer-3 view of one router and the prefixes it routes. The subnet nodes are derived, so --kind router keeps the prefixes the surviving routers are addressed in and never an empty one:

$ netviz -i examples/home-lab render --layer l3 --kind router -f mermaid
flowchart TB
    n0(["rtr-home<br/>[router]<br/>vlans: 10"])
    n1("192.0.2.1/32<br/>[ipv4 subnet]")
    n2("192.168.10.0/24<br/>[ipv4 subnet]<br/>vlans: 10")
    n3("203.0.113.0/30<br/>[ipv4 subnet]")
    n4("2001:db8::1/128<br/>[ipv6 subnet]")
    n5("2001:db8:10::/64<br/>[ipv6 subnet]<br/>vlans: 10")

    n0 -- "lo0 · 192.0.2.1/32" --- n1
    n0 -- "lo0 · 2001:db8::1/128" --- n4
    n0 -- "wan0 · 203.0.113.2/30" --- n3
    n0 -- "lan0 · 192.168.10.1/24" --- n2
    n0 -- "lan0 · 2001:db8:10::1/64" --- n5

    classDef router fill:#dbe9f6,stroke:#2563eb,stroke-width:1px
    classDef subnet fill:#e0f2f1,stroke:#0f766e,stroke-width:1px
    class n0 router
    class n1,n2,n3,n4,n5 subnet
rendered 6 node(s) and 5 edge(s) as mermaid at layer l3

A warning is emitted when a flag cannot reach the format you picked, rather than the flag being dropped in silence:

$ netviz -i examples/quickstart render --icons cisco -f mermaid
flowchart TB
...
warning: --icons is ignored for mermaid output, which has no picture to put an icon in; the formats that draw icons are dot, svg, html, png, pdf
rendered 3 node(s) and 2 edge(s) as mermaid at layer l1

The everyday invocations, illustrative paths and all:

netviz render -f json | jq '.nodes[].name'
netviz render -f mermaid -o docs/topology.mmd
netviz render --vlan 10 --layer l2 -f svg -o vlan-10.svg
netviz render --layer l3 -f svg -o subnets.svg
netviz render --layer power -f svg -o power.svg
netviz render --neighbors-of sw-dist-01 --depth 2 -f svg -o around-dist.svg
netviz render --kind switch --kind router --group-by-namespace -o core.dot
netviz render --collapse-depth 1 --group-by-namespace -f svg -o overview.svg
netviz render -f html --layer l1 --layer l2 --layer l3 -o topology.html

Retyping none of it

Every option except -o/--output, --force and --show-config can be given a default in netviz.toml, so a team retypes none of them — see [render] and the full key list. A key is the long flag without its leading dashes.

--profile NAME applies the [profile.NAME] block on top of [render]; explicit flags still win over both. --show-config prints the settings this invocation resolves to, and where each one came from, then exits without doing any work — which is the fastest way to find out why a diagram does not look the way you expected.

Arguments

Takes no positional arguments.

Options

Flag Value Default Meaning
-f, --format [dot|svg|html|png|pdf|mermaid|json] dot Output format. dot: Graphviz DOT source; svg: SVG image, via Graphviz; html: self-contained interactive page, via Graphviz; png: PNG image, via Graphviz; pdf: PDF document, via Graphviz; mermaid: Mermaid flowchart, for embedding in Markdown; json: node-link JSON, for downstream tooling.
-o, --output FILE — Write to this file instead of stdout.
--namespace NS — Keep only elements in this namespace or below it. Repeatable.
--vlan VID — Keep only elements participating in this VLAN. Repeatable.
--kind [switch|router|firewall|hub|computer|server|adapter|patchpanel|pdu|user|group] — Keep only elements of this kind. Repeatable.
--name GLOB — Keep only elements whose name matches this glob. Repeatable.
--neighbors-of NAME — Keep only the neighbourhood of this element.
--depth INTEGER, >= 0 1 How many hops --neighbors-of reaches.
--select QUERY — Keep only the elements this query selects, e.g. "kind = switch and not has vrf". The flags above are sugar for the equivalent query and are combined with it; 'netviz query --explain' prints which. See docs/query.md.
--collapse NS — Replace this namespace and everything under it with one node, labelled with what it holds. Links crossing the boundary attach to it; links inside it are counted rather than drawn. Repeatable.
--collapse-depth N — Collapse every namespace N levels deep, counted from the shallowest one that branches: '--collapse-depth 1' is the site-level overview of a tree laid out as sites//.
--bundle-links, --no-bundle-links — — Draw parallel links between the same pair of elements as one edge, with the count in the label. Members of a declared 'lag' interface are bundled either way unless --no-bundle-links is given, since the inventory already says they are one logical link.
--show-ips, --no-show-ips — --show-ips Print configured IP addresses on the nodes.
--show-vlans, --no-show-vlans — --show-vlans Annotate nodes and links with VLAN membership.
--annotations, --no-annotations — --annotations Draw the notes, areas and legends the inventory declares for this view. Turn them off for a diagram that should carry the topology and nothing written about it — a printed page for an audit — and leave them on for one that is being read rather than checked, where the callout is the reason the screenshot is worth attaching to the ticket.
--group-by-namespace — off Draw each namespace as a visual group.
--icons THEME|DIR — Draw each element as an icon instead of a plain shape. Built in: cisco, none. A directory of images named after element kinds (router.svg, switch.png, ...) also works. Graphviz formats only.
--theme NAME|PATH — Apply a stylesheet: selectors by kind, name, namespace, role or label, each mapping onto a style block. Built in: blueprint, mono, none. A path to a 'kind: theme' YAML file also works. An element's own spec.style still wins.
--style, --no-style — --style Honour the styles the inventory and the theme declare. --no-style draws the plain diagram from the built-in palette alone, which is the way to read a topology whose stylesheet is in the way. Icons are unaffected: use --icons none.
--tooltips, --no-tooltips — --tooltips Carry the full detail of each element — interfaces, addresses, VLANs, cabling — as hover text. Reaches a reader in svg output; png and pdf have nowhere to put it.
--link-template URL — Link each element back to the YAML that declares it, e.g. 'https://git.example.com/net/blob/main/{file}#L{line}'. Placeholders: {file}, {line}, {name}, {namespace}, {kind}. dot and svg only.
--element-ids — off Give every node, edge and namespace a stable id derived from its name, so the diagram can be deep-linked and styled from outside. dot and svg only.
--max-addresses N 4 Longest address list spelled out under a node before it is abbreviated to 'and N more'. 0 prints the count alone.
--rankdir [tb|lr|bt|rl] TB, top to bottom Layout direction. A wide network reads better left to right; a deep one top to bottom. Honoured by the Graphviz backends and by mermaid.
--routing [spline|orthogonal|straight] whatever the inventory's layout documents say, else spline How links are drawn between the bends they are pinned through: 'spline' is the curve Graphviz draws, 'orthogonal' right angles, 'straight' segment to segment. A default: a link that pins a style of its own keeps it. Honoured by the Graphviz backends, the JSON export and the editor. 'netviz layout --write' records it in the view it arranges, so the choice is the inventory's rather than the command line's from then on.
--avoid, --no-avoid — avoid Route orthogonal links around the boxes they are not attached to instead of straight across them. Only applies to an arranged diagram drawn with '--routing orthogonal': a spline has nothing to route around, and an unarranged one is routed by Graphviz, which already avoids nodes. A bend you placed yourself is never moved — routing fills the segments between them. '--no-avoid' is the local Z-and-L every orthogonal diagram was drawn with before this existed.
--title TEXT — Caption for the diagram.
--layer [physical|l1|l2|l3|ipam|overlay|routing|rack|power|identity|netns|security] l1 l1 draws the physical topology; l2 annotates it with VLANs; l3 draws IP subnets and the elements addressed in them; ipam draws the address plan — the same prefixes without the devices, nested inside the blocks they came out of and showing how full each is; overlay draws the tunnels; routing draws the BGP sessions and OSPF adjacencies, clustered by VRF; physical adds the patch panels l1 splices out; rack draws a front elevation per rack; power draws the PDUs and the feeds into everything they power; identity draws the users and groups; netns opens each machine up into the network stacks inside it, joined by their veth pairs; security draws the firewall zones and what the policy lets cross between them. Repeatable for -f html, which draws each layer and puts a switcher over them.
--strict — off Treat warnings as errors.
--force — off Proceed even when validation failed. The result may not match the files.
--profile NAME — Apply the [profile.NAME] block of netviz.toml on top of its [render] table. Explicit flags still win over both.
--show-config — off Print the settings this invocation resolves to, and where each one came from, then exit without doing any work.

Exit codes

Code Meaning
0 The diagram was produced.
1 The inventory was rejected: validation found errors (or, under --strict, warnings) and --force was not given.
2 Usage error, or an unusable netviz.toml — including two --layer values for a format that holds one, and --layer rack with -f mermaid.
3 The inventory could not be discovered or read at all.
5 The rendering could not be produced: Graphviz is missing, the output path is not writable, or a binary format was aimed at a terminal.
130 Interrupted.
141 The downstream end of a pipe closed first.

See also