netviz watch

netviz watch re-renders whenever a file in the inventory changes, optionally serving the result on a page that reloads itself. Every cycle is the same load, validate and render netviz render performs, followed by a timestamped status line and any findings. It is the command to leave running in a second terminal while you edit YAML in the first.

Synopsis

netviz [GLOBAL OPTIONS] watch [OPTIONS]

The status line

One line per cycle, with the time, the status and what came of it:

09:41:02  ok       23 nodes, 26 edges → topology.svg (128 ms)
09:41:37  invalid  1 error; keeping the render from before
errors (1):
  sites/hq/links.yaml#0:12  E001  cable 'sites/hq/cbl-07' endpoint sw-hq:port9: no element named 'sw-hq' is declared in this inventory

A failed cycle changes nothing. The file written by --output keeps its last valid contents and the preview keeps serving the last valid diagram, so a half-typed document never blanks the picture you are working from — which is why the line says keeping the render from before rather than reporting a size of zero. Nothing ends the loop except Ctrl-C: a syntax error, a deleted root, a --neighbors-of target that no longer resolves are all statuses, not crashes.

With --output the file is rewritten atomically, so a reader — a browser with the SVG open, a static site build — sees the old diagram or the new one, never half of each. Naming a file inside the tree being watched is fine: the render's own output is excluded from the watch, which is what keeps the loop from feeding itself forever.

Giving neither --output nor --serve is allowed and warned about: each render is then checked and discarded, which is occasionally what you want and usually not what you meant.

What triggers a render

Only YAML documents, netviz.toml and .netvizignore trigger a render; an editor swap file or a rendered diagram does not, and neither does anything under a directory the loader skips (.git/, _drafts/, …) — the same rule the loader itself applies, so what the watcher reacts to is what the inventory contains. A single-file inventory is watched through its directory, because editors replace a file rather than rewrite it and a watch on the file itself would not survive the first save.

--debounce is how long a burst of filesystem events is collected before re-rendering. One editor save is several events — a temporary file, a rename, a metadata change — and re-rendering each of them would render three times and show the middle one.

The default is 300 ms on Linux and 700 ms on macOS and Windows, because the window has to be wider than the span those events arrive over and that span belongs to the backend rather than to the editor. inotify delivers each event as it happens, so one save lands within a millisecond or two. FSEvents coalesces and delivers on its own schedule, and ReadDirectoryChangesW spreads a save-by-rename noticeably further — often as two bursts, which at 300 ms would be two renders for one keystroke.

Raise it for a large inventory, lower it if you want the diagram to keep up with you and do not mind the occasional double render.

Every render option applies

Every filter and display option of netviz render applies here too — --tooltips, --link-template and --element-ids included, which is what makes watch -f svg -o topology.svg keep an interactive diagram up to date. -f html works the same way, repeated --layer included, so watch -f html -o topology.html --serve gives you the whole interactive page, re-rendered as you type. -f defaults to svg here rather than dot, because a live preview wants a picture.

docs/rendering.md explains the layers, the filters, the aggregation and the display options themselves; this command adds nothing to them and changes none of their defaults.

The live preview

--serve also hosts the render over HTTP. The page polls once a second and swaps the diagram in when it changes — polling rather than server-sent events keeps the client a dozen lines of dependency-free JavaScript.

The preview is bound to loopback and stays there unless you say otherwise. An inventory describes internal network topology — addresses, VLANs, what is plugged into what — so --host is the explicit act of publishing it, and doing so prints a warning. The server answers GET and HEAD on five fixed routes, never turns a request path into a file name, and refuses a request that reached a loopback preview under a foreign Host header. It is a development server: do not put it on a hostile network.

--host and --port describe that server, so both require --serve; given without it they are a usage error rather than a flag that appeared to work and never did. --port 0 lets the operating system choose one, and the address actually bound is printed.

netviz watch --serve                                   # preview at http://127.0.0.1:8080/
netviz watch -f svg -o topology.svg                    # just keep a file up to date
netviz watch --serve --layer l2 --vlan 10 --title vlan10
netviz watch --serve --host 0.0.0.0 --port 9000        # deliberate, and warned about

Arguments

Takes no positional arguments.

Options

Exit codes

A watch is ended by Ctrl-C, which is how the command is meant to finish and not a failure. Everything an inventory can do wrong is a status line instead of an exit status.

See also

• netviz render and docs/rendering.md — the render every cycle performs, and every option this command inherits.
• netviz web — the same live feedback for a document stream you edit in the browser rather than a tree you edit on disk.
• docs/validation.md — the findings a cycle reports, and what --strict promotes.