netviz web

netviz web opens an inventory in the browser and draws it as you edit it, with an info box on every node and link. It has two faces, and which one you get is decided by what you point it at:

• a folder — an editing session. The server holds the loaded tree, the page lists its files and the documents in them, and with --write the browser can change them. This is the one to use for an inventory.
• anything else — a file, a pipe, or nothing — a scratchpad. One YAML document stream, held in the browser, rendered as you type, written nowhere. This is the one to use for a snippet or a paste.

Synopsis

netviz [GLOBAL OPTIONS] web [OPTIONS] [SOURCE]

_{Hovering sw-home in examples/home-lab: every port, its addresses and VLAN mode, and what each one is cabled to.}

The editing session

netviz web ./inventory                # read-only: browse the tree and its diagram
netviz web ./inventory --write        # read-write: save, undo and redo from the page

The window is three panes. On the left is the inventory: every file the loader would read, grouped by namespace, with the documents each one declares listed under it by kind and name. In the middle is the file being edited and the problems found in the tree. On the right is the diagram.

The panes are wired to each other, which is the point of the command:

• Selecting a file opens it, whole, in the editor.
• Selecting a node in the diagram reveals the document that declares it — the right file, scrolled and selected at the right line. The shape carries the element's address, the address is in the file list against a file and a line, and that mapping comes from the same load the diagram was built from.
• Clicking a problem navigates to its file and line, opening the file if it is not the one on screen.
• A problem with a mechanical repair grows a fix button, which applies it as one logged, undoable gesture. Where a rule admits two repairs there are two buttons and no default, because choosing between them is not the tool's to make. It is the same catalogue netviz validate --fix uses, under the same gate: the repair is thrown away unless re-validating shows the finding gone and no rule reporting more than it did. Fixing a finding lists them.

Every file's state is shown as it is, not as it would be convenient. A file you have typed into is unsaved. A file that changed on disk while you had unsaved edits in it is conflict, and netviz will not resolve that for you: it says so and leaves both versions alone until you decide. A file that was deleted underneath you says deleted on disk.

Three consequences of that, because they are the ones people meet:

• Saving text that is already on disk still clears the badge. Nothing is written — the bytes are the bytes — but the badge is about the gap between the pane and the file, and there is none.
• A gesture on the diagram is applied to the file, not to the pane. If you have unsaved edits in the file it rewrites, the change goes to the file and the pane becomes a conflict holding your text. It is the same rule as an edit made in $EDITOR: unsaved text is never thrown away to make a picture tidy.
• Deleting an element closes its file if the pane was showing it and had nothing unsaved in it — an editor still offering to save a document you just deleted is one Ctrl-S away from putting it back. With unsaved text in it the pane stays, badged deleted, because that text is now the only copy.

A conflict is resolved by saving again, which is what the message offers: the second save is a write over the version you were told about, not over whatever happens to be there when it lands. If the file moves a third time in between, it is refused again — the precondition is never dropped, only re-aimed.

The guided tour

The first time you open a session, the page offers a sixty-second tour. Take it with Enter, decline it with Esc — declining is remembered, and Ctrl-K → Take the guided tour runs it again whenever you want it.

It creates a device, cables it to one of yours, moves its document to another file, opens the changes drawer on the YAML all three wrote, and undoes the lot. The point is the mapping: every shape on the canvas is a document, so a shape cannot appear without a file appearing, and undoing the gesture brings the bytes back.

It never touches your inventory. Starting the tour copies the tree — only the documents the loader reads, plus netviz.toml — into a temporary directory and points the page at a second session over the copy. That session is always writable, so a read-only netviz web DIR can take the tour too; the panel names both directories so there is no doubt which one is being written. Finishing, skipping or closing the tab deletes the copy, and so does stopping the server.

Any step may be refused — it is the real write path, and it is allowed to say no. The tour shows the refusal and carries on to the next card.

Writing

--write is off by default, and it is refused unless the server is bound to loopback — publishing an endpoint that changes your inventory is not something a flag should let you do by accident. Without it every read works and every write answers 403.

With it:

• Ctrl-S writes the open file back. The write carries the content hash the file was read at; if the file moved underneath, the save is refused and shown as a conflict rather than overwriting the other edit. Saving again after that overwrites deliberately.
• Ctrl-Z / Ctrl-Y undo and redo. The stack lives on the server, so it survives a page reload and a second tab sees the same history. Each entry is the exact inverse the mutation layer produced, so an undo restores bytes — the comment style, the quoting and the reference spellings of every document a rename rewrote.
• A change that would break the tree is refused, listing the problems, and can then be written anyway. This is the same gate netviz edit applies: an inventory that already fails validate can still be edited, one that would gain a new error cannot without saying so.

Every write goes through netviz.edit — the same typed, reversible, comment-preserving operations netviz edit applies from the command line. The server constructs no YAML of its own, so untouched lines are not rewritten and a diff of an edit shows the edit.

Reviewing what you changed

The Changes button opens a drawer listing every gesture the session made, newest first. One entry per gesture rather than per operation: deleting a switch is one line, not the five operations it became. Each carries

• the YAML hunk it wrote, as a unified diff with a/–b/ prefixes, so it pastes into a patch file without editing;
• its label, which reveals the document it changed at its line — the same mapping a click on the diagram uses, run from the log instead;
• Revert, which puts that one change back.

A revert is a new change, not a rewind. It applies the gesture's own inverse as a fresh edit, which is itself logged and itself undoable, so reverting the third of ten gestures leaves the other nine alone. When one of those nine depended on what the third one did, the revert is refused with the reason and nothing is written — which is the honest outcome, and the one an undo stack cannot give you.

Opening the drawer also repaints the canvas as a diff: added elements green, removed ones red and dashed but still in place, changed ones amber with a badge naming the fields that moved, everything untouched faded. The since menu chooses what it is drawn against —

It is the same overlay netviz diff draws, from the same changeset — the drawer and the diagram are two views of one answer.

Copy commands hands the whole session over as a list of netviz edit invocations, in the order they happened, for a pull-request description or somebody else's terminal. The rendering is never lossy; see docs/editing.md.

The history timeline

The inventory is a folder of YAML in a repository, so its whole history is renderable. History, above the canvas, opens a scrubber along the bottom of it, over the commits netviz log lists — and the diagram becomes the diff each one carries against its parent as you step:

 ▶  ◀◀  ────────────●───────  ▶▶   Now   ×
 e58b3c3a0  Add a lab switch   Scrubber · 2026-08-14   1 device added

Oldest on the left. Beside the control is the commit itself — the abbreviated hash, its subject, its author and date, and the one-line summary of what it did to the network — because a picture with a hash under it places nothing in time.

Each frame is arranged the way that revision arranged it. Both sides of the diff are read out of the commit, layout document included, so a diagram that was hand-placed in March is still hand-placed when you scrub back to March — and one placed since is not retro-fitted onto a picture that never had it.

The history and the changes drawer are two overlays on one canvas, so opening either puts the other away. The legend means the same four things in both.

What it will not pretend

• A revision whose inventory does not load stops the playback and says which revision and why, in the place the summary would have gone. It is not skipped: a commit that broke the tree is the one worth stopping on.
• A revision from before the inventory existed is an empty network, not an error, so the commit that first added the folder reads as the whole network arriving — noted as such beside the summary.
• A repository with more history than the bound is truncated to the newest, and the bar says "the newest 100 of 312 revisions" rather than implying that is all there ever was. The bound is [history] max-revisions in netviz.toml, 100 by default; see netviz log, where an explicit range wider than it is refused outright rather than truncated.
• A tree that is not in a repository says so where the commit would be, rather than offering a control that does nothing.

What it costs

A frame is one inventory read, one changeset and one Graphviz layout — the same work drawing the tree at all costs, plus the read and the diff. Two things keep that interactive:

• Rendered frames are cached by tree hash, in pairs: the before tree and the after tree. Scrubbing back over ground already covered is a dictionary lookup, and so is a revert, a cherry-pick or a rebase that lands on a pair of trees already drawn.
• Neighbouring revisions share their loaded state and their parsed files. Stepping reads one revision rather than two, and the parse cache means that read parses the files the commit touched rather than the two thousand it did not.

tools/bench_history.py measures it. On the 1056-device benchmark tree, where one plain render of the working tree is about 1.5 s, a step is about 1.5× that and a frame already drawn comes back in about 13 ms.

Reconciliation

The session does not own the files. watchfiles watches the folder exactly as netviz watch does, so an edit made in $EDITOR, a git checkout, or a second netviz process bumps the tree revision — and the page is told, over a server-sent-events stream, the moment it happens. If the watch cannot start, the command says so rather than leaving a page that is quietly stale.

The event says what moved, which is what makes the page's response proportionate to the change:

• a save of one file refetches that file's row, not the file list;
• a revision that does not change the drawing of the layer on screen does not redraw it — the page sends the fingerprint of the picture it is showing and the server answers "unchanged" rather than running Graphviz. Editing a description on a 1056-device tree went from 1.7 s to 185 ms; see docs/follow-ups.md entry 18 for the harness and the numbers.

The stream is an optimisation, and the page works without it. A proxy that buffers responses, a browser without EventSource, a stream that will not open: any of them drops the page back to polling /api/state once a second, which replays the very same events out of the server's ring buffer. The indicator above the file list says which of the two you are on. Nothing is writable through the stream and no write depends on having read one.

More than one client

A session is shared — two tabs, or two people on the same machine — and it says so rather than leaving them to collide:

• every connected page is listed above the file list, with what it is looking at and what it is editing in the tooltip;
• what somebody else has selected is drawn on the canvas as a faint dashed halo, distinct from the highlight your own hover gives;
• a file somebody else has unsaved edits in is badged in use.

All of that is advisory. It blocks nothing: the row still opens, the file still saves, and presence expires by itself if a tab goes away without saying so. The only things that can refuse a write are the ones that are checks on the tree itself — the content hash of a whole-file save and the tree revision of an operation batch. A soft lock built on a heartbeat would be a way to lock an inventory by closing a laptop lid.

So the conflict story is unchanged by having company: two clients saving the same file gives the second a 409 carrying what is really on disk; a save racing an $EDITOR write gives the same; and an undo issued in one tab rewrites the files and moves the buttons in the other, which is what a server-side history means.

The API

The page is a client of a small JSON API, and so can anything else be. All of it is on loopback and none of the write routes exist unless --write was given.

<path> is relative to the inventory root and is checked, not normalised: an absolute path, a .., a component the loader skips and a suffix that is not YAML are each refused by name. No other request ever becomes a file name.

Right-clicking

Right-click the diagram and you get the handful of commands that make sense where you clicked. On an element, on a link, and on the paper between them — three menus, listed below.

Two things it is not. It is not a second set of gestures: every row runs a command from the table under that command's own id, so the menu, the palette and the key are three ways to the same one implementation. And it is not a full list: the palette is one keystroke away with all fifty in it, and a menu long enough to need reading has stopped being quicker than typing. All commands… is the last row of the canvas menu for exactly that.

What it does add is a target. Right-clicking a shape focuses it first, so Delete it deletes the one you pointed at rather than the one the keyboard was left on, and the menu's heading is the element's address so there is no doubt which that is. Every row also prints its own shortcut, the same way a palette row does: use the menu for a week and you will not need it.

A row that cannot run now is greyed, with the reason on it — this session is read-only; restart it with --write — rather than missing. Escape closes it, the arrow keys walk it, and Shift-F10 or the menu key opens it on whatever the diagram has focused, because a menu only a mouse can open is a set of commands a screen-reader user does not have.

Right-clicking a bend on a link still removes that bend, and shows no menu: the handle is a control of its own, and burying its one gesture two rows deep would be a loss. Right-clicking anywhere off the canvas is the browser's own menu, untouched.

Right-clicking a multi-selection

Right-clicking an element

Right-clicking a link

Right-clicking a note, an area or a legend

Right-clicking a namespace box

Right-clicking the canvas

New ▸ opens one row per element kind, and picking one opens the create form with that answer already filled in — the same form n opens, writing the same document through the same netviz edit create.

The keyboard

Everything this page does is reachable without a pointer, and the page says so out loud rather than making you find out. There are three ways in, and they are three views of one table:

• Ctrl-K — the command palette. Every command below, fuzzy-matched by name, plus everything the page can go to: every element address in the diagram and every file path in the inventory. Each row prints its own shortcut, so the palette is also how the bindings are learnt. A command that cannot run now is shown greyed with the reason — "this session is read-only; restart it with --write" — rather than quietly missing.
• ? — the shortcut sheet. The table below, in a dialog.
• the keys themselves.

A fourth, for the pointer: right-clicking the diagram offers the few of these that fit what is under the cursor, each row printing the chord that also runs it.

A chord written Ctrl-… means the platform's command modifier: ⌘ on a Mac. A single letter is a canvas gesture and fires only while the diagram has focus — n creates a device there and types an n in the YAML pane, which is the distinction the Where column makes. v and h are the two exceptions: which pointer tool is up is a question about the mouse, not about what the keyboard last landed on, so they answer from anywhere but a text field.

The pointer tool

A drag across the paper means two things and both are right: to one person it is a region being selected, to the next it is the paper being moved. Nothing in the gesture tells them apart, so — as in every drawing tool — it is a mode, and the toolbar above the canvas says which one:

The cursor is the other half of the answer: an arrow under the selection tool, an open hand under the pan tool, closed while the pan is happening. It is the hand everywhere inside the canvas — over a switch and over a bend handle as much as over the paper — because that is exactly where the two tools differ.

Neither is ever more than a modifier away, which is what keeps the mode from being a trap:

• Hold Alt and the other tool takes that one gesture. Alt-drag bands while the hand is up and pans while the arrow is; the tool is where you left it when you let go. (This is the same Alt-drag that panned before there was a mode, so nothing anybody's fingers already knew has changed.)
• The middle button always pans, whichever tool is chosen.
• Clicking still selects under either tool. Only dragging is the mode — and a pan that actually travelled swallows the click behind it, so letting go over a switch does not open it.

Right-clicking the canvas offers both tools, because the press that wanted the other one has already happened over the diagram and the toolbar is at the far corner of it.

Driving the diagram

Tab reaches the canvas like any other control; the diagram is one stop on the page's tab order and never a trap. From there the arrow keys walk it, preferring the elements the focused one is linked to, so a path is followed rather than a grid swept. Enter opens the inspector — and, in a session, the document that declares the element, at its line. n, c and Delete are the create, connect and delete gestures; each opens a small prompt whose element field is already filled in with whatever is focused, so the same command works from the palette with nothing focused at all.

Two rings, deliberately different: focus is a solid violet halo — where the keyboard is — and selection is a long dash, with somebody else's selection a short one. Three patterns, not three shades, so they are told apart without colour.

Delete takes what cannot survive

On the command line, deleting a cabled switch is refused and you are told to pass --cascade. On a canvas that would be theatre: somebody who dragged a box to the bin has already said what they want, and a gesture that stops to ask for a flag it will then be given is a gesture with one extra step in it. The editor always cascades. What it owes you instead is the truth about what that costs, before the fact and once:

Delete 1 element?

switches/sw-home

These cannot survive it and go too: cables/cbl-rtr-sw — one end of it is switches/sw-home:port1 …

8 layout entries that placed them are dropped.

This is one change: Ctrl-Z puts all of it back.

That list is not read off the picture. GET /api/cascade asks netviz.edit for the set it will actually remove, so it includes the things a diagram cannot show you: the tunnel three levels up that runs over a cable that runs to the switch, the note anchored to it in a view you are not looking at, the group that lists it as a member, and the coordinates in every kind: layout document that placed any of it. A client-side guess would get the cables right and everything else wrong.

A delete that takes nothing but what you named does not ask at all — a confirmation that always appears is one that stops being read. Deleting an uncabled spare switch, a note, an area or a legend is immediate.

And the whole of it is one entry in the undo stack: the elements, the annotations and the geometry go together, and one Ctrl-Z brings them back byte for byte, comments included.

Selecting several things

Most of the editor acts on a selection, and a selection is a set:

The selection is held as element addresses, not as shapes, which is what lets it survive a redraw — a save, an undo, somebody else's edit — and lets a culled element half a screen away stay in it. The ring is drawn for the ones on screen; the count is on the diagram outline, where a screen reader hears "8 elements, 3 links, 2 selected" and each selected entry as pressed.

With more than one thing selected, the gestures that can mean a set act on all of it, as one change:

• Delete asks once — listing what goes — and writes the lot as a single entry in the undo stack. One Ctrl-Z puts all of it back. See Delete takes what cannot survive.
• Set a field, Remove a field and Move to another file apply to every selected element in one batch, so twelve switches gain spec.site in one validated, conflict-checked write.
• Align, distribute and snap to grid appear, from the palette or by right-clicking inside the selection. Each writes one reviewable diff into the kind: layout documents that hold the arrangement — see docs/editing.md — and the grid pitch is the inventory's [editor] grid.

Right-clicking inside a multi-selection opens the selection's own menu rather than the element's: the subject is the set, and "Rename it…" on eleven shapes would have to mean whichever one the pointer happened to be over.

A thousand devices

Above four hundred elements the canvas stops drawing all of them at once. Two things happen, and both are visible:

Only what is on screen is drawn. Everything more than half a screen outside the viewport keeps its place in the document and loses its contents until you pan back to it. The status line says so — drawing 140 of 2106 in view (pan, or Ctrl-K to find) — because a canvas that is quietly missing things is worse than a slow one. Nothing about reaching an element changes: the arrow keys, the outline, the command palette and find-in-diagram all work from the records rather than from the drawing, so selecting something on the far side of the diagram brings it back and pans to it.

Zoomed out, the labels come off. Below the scale at which a device name is a smudge, the names and the icons are dropped and each namespace grows a dashed frame with its name and how many elements are in it. Zoom back in and they return. The zoom range is the drawing's own, not a fixed multiple, so a label on a thousand-device diagram can always be reached.

The first layout of an inventory that size is a real Graphviz run and takes a second or two; the status line counts while it happens rather than sitting still. If a redraw after dragging a node feels slow, it is: a diagram with some positions stored has to be laid out twice, and netviz layout --write places the rest and takes the redraw to a fraction of it. The measured ceilings are in docs/follow-ups.md entry 20.

Routing a cable

A link is geometry as much as a node is (docs/schema.md §18), and once the view is arranged it can be routed here. Click a link to select it; double-click the line to drop a bend where you clicked; drag a bend to move it; drag the hollow midpoint handle to insert a bend and place it in one motion; right-click a bend to remove it. A label the inventory has already pinned gets a handle of its own, which slides it along the route and lifts it off.

Each of those is also a command, because a bend that can only be placed with a mouse is a bend somebody working from the keyboard cannot place at all: b adds one half way along the selected link, Shift-B straightens it, r sets its routing style — spline, orthogonal or straight, on this link alone — and the palette puts a moved label back on the line. On a view that is not arranged they refuse with the fix, netviz layout --write, rather than doing nothing: a diagram Graphviz is still routing has nowhere to keep a bend.

Nothing here is a browser-side model of the arrangement. Letting go of a handle posts one set-link-geometry operation (docs/editing.md), the server rewrites the kind: layout document through the same comment-preserving path netviz layout uses, and the canvas repaints from the render that follows — so what you see here is what netviz render draws, and the gesture is one entry in the changes drawer with a YAML hunk under it. The line under the cursor is drawn by a port of netviz's own router, which tests/test_browser.py runs against the Python it mirrors on every CI run, so a drag cannot land somewhere the render would not.

Writing on the diagram

The commentary of docs/schema.md §21 — a callout, a zone, a key — is edited here the way a cable's route is. Shift-N drops a note at the pointer and opens it for typing; right-clicking an element or a link and choosing Note about it… anchors the note to that instead, so it follows the device when the diagram is laid out again. A note is retyped by double-clicking it, or with Shift-E on a selected one: Ctrl-Enter or clicking away writes it, Escape leaves it alone. Dragging a note moves it, its corner resizes it, and a zone pinned to a rectangle is dragged by its outline and resized by its corners. Delete removes whichever is selected. Alt-N hides the lot, which changes no file: commentary is never topology, so it is a way of looking at the diagram rather than a way of changing it.

A zone drawn round its members has no box to move — it is wherever those devices are — so dragging it is refused with that sentence rather than quietly turned into a rectangle. Everything else lands as one create-annotation, set-annotation or delete-annotation batch through /api/ops, which is one entry in the changes drawer and one Ctrl-Z; the rules are in docs/editing.md.

Without a screen

The rendered SVG is inert by default: Graphviz emits shapes, not semantics. This page adds them from the same records the info box is built from, so there is one description of an element rather than two that drift:

• every node and link carries a role and an aria-label — "sw-home, switch, 8 interfaces, linked to rtr-edge on eth0";
• the canvas is an application that says which element is current, so arrowing around it is announced;
• Alt-4 opens the outline — the whole view as a list, one line per element, which is both the screen-reader fallback and the fastest way to find something by name. It is off screen until focused and a real panel once it is;
• every applied, refused and reverted gesture is announced in a live region, once. A refusal interrupts; everything else is polite.

The interface follows prefers-color-scheme with a palette per scheme — every colour clears 4.5:1 against its own background, which a single palette used on both cannot — and honours prefers-reduced-motion. Where a colour carries meaning it is never alone: the diff legend prints +, ~ and −, the same sigils the diagram draws, and the three diff line styles differ as well as the three hues.

tests/test_browser.py runs axe-core over the page on every CI run and fails on a new WCAG 2.1 AA violation, and drives one end-to-end test — create a device, cable it, undo both — without dispatching a single mouse event.

The bindings

Everywhere

Moving around

Editing the inventory

Arranging the diagram

The view

Files and history

The scratchpad

netviz web                                  # opens on the netviz init example
netviz web devices/sw-office.yaml           # seeded from one file
kubectl get cm topology -o jsonpath={..yaml} | netviz web   # or from a pipe

The left pane holds a document stream — one or more documents separated by --- — and re-renders about half a second after you stop typing. Nothing is written. The seed is read once, at startup; after that the stream lives in the browser and every pass happens in memory, so the command cannot damage the file it was seeded from and equally will not save your work: copy the text out before you close the tab.

A stream has no folders and therefore no namespaces, and no file to write back to. That is why --write is refused here and why a folder opens a session instead.

Both faces

Hovering a node or a link opens an info box holding what the diagram has no room for: every interface with its type, MAC, MTU, addresses and VLAN mode; every link that terminates on the element, what it runs to and over which port; and, at layer 3, the prefix a subnet node stands for and who is addressed in it. Everything it shows is the same data netviz render -f json exports — the records are that export — so the two cannot drift apart, and they are the same records a committed SVG carries as tooltips (docs/rendering.md). The element under the pointer and everything it touches are lifted out of the diagram while the box is open; click to pin the box, click again or press Esc to let go.

Beyond that: the layer, the VLAN filter and the display toggles are in the header and apply on the next render; the canvas zooms with the wheel and pans with a drag under the pan tool, the middle button, or Alt; and the splitter between the panes moves.

Broken text still draws. netviz render refuses an inventory with errors unless --force, because a diagram that disagrees with the files misinforms whoever is shown it. Here the diagram is the feedback and text being edited is wrong most of the time, so every problem is listed with its file and line and whatever resolved is drawn anyway.

netviz.toml decides how this machine draws: the [render] table and --profile of the inventory named by -i — the current directory by default — supply the settings this command has, --icons above all. A session also reads the [validate] table of the folder it has open, so the problems it lists are the ones netviz validate would list in that tree; a stream has no folder of its own to look in and uses the built-in defaults plus the strict toggle in the header.

Icons

The icons box in the header draws every device as its picture instead of as a plain shape, and unticking it puts the shapes back — no restart, no flag, and no reload. It is the question somebody asks while looking at a diagram, so it is answered where they are looking.

The split is deliberate, and it is the same one --write makes. Which themes exist is the command line's to say, because a theme is a directory of images on this machine and a page has no business naming one: --icons DIR puts your own directory on the list, and --icons cisco — or nothing at all — leaves the set that ships with netviz. Whether this drawing uses one is the browser's, because that is a fact about the picture and about nobody's filesystem. So the switch offers exactly what the server was started with, /api/state says what that is, and a request naming anything else is refused with the list it could have named.

A directory theme is offered to the page as custom, not as its path: the switch has to be able to ask for it again after turning it off, and the name it uses to do that should say nothing about the filesystem the server is running on. Only this server maps custom back to the directory.

--icons therefore sets where the switch starts rather than overriding it: a session started with --icons cisco opens with icons on and can still turn them off, and one started without can still turn them on. ?icons=cisco, ?icons=custom and ?icons=none do the same thing in an address bar, like every other view toggle.

The server

The same restrictions apply as to the watch preview — loopback by default, so publishing the interface with --host is an explicit act and is warned about; a fixed set of routes; no request path ever turned into a file name; a Host header check that keeps a loopback bind from being reached through a rebound DNS name — plus three of its own: a request body is capped at 1 MB, the SVG is parsed and stripped of anything that could execute or navigate before it is put into the page, and no write route exists at all without --write on a loopback bind. It is a development server: do not put it on a hostile network.

The event stream and presence, against the same threat model

Both are new surface, and both are held to the rules above rather than excused from them.

• Same bind, same Host check. /api/events and /api/presence are ordinary routes on the same handler, so a request that reached a loopback bind under another name is refused with 421 before either is entered. A page on a hostile origin therefore cannot open the stream and read your topology out of it — which matters more here than elsewhere, because a stream keeps delivering. connect-src 'self' in the Content-Security-Policy says the same thing from the other side.
• The stream is read-only, and so is presence. Nothing about the inventory can be changed through either. /api/presence writes to an in-memory list and is the one route a read-only session still accepts, because "who else is looking" is useful to two people browsing and touches no file. On a bind you published with --host, anyone who can reach it can read the stream and add themselves to that list — which is a nuisance rather than a compromise, and one more reason publishing is an explicit act.
• A client id is a name, never a permission. Ids are issued by the server and a request that invents one gets a fresh identity rather than somebody else's entry. The id travels with a write only so the page can recognise its own change in the events and skip a reload; nothing is authorised by it, and a request that claims another client's id can do nothing this one could not.
• Neither is unbounded. At most 32 streams and 64 clients per session, at most 64 selected addresses and dirty paths per client, a 256-event ring buffer, and a subscription that falls 64 events behind is resynchronised rather than buffered. A page in a reload loop cannot make the process grow, and a stalled tab cannot make it grow on that tab's behalf.
• Presence expires. Entries go after 45 s of silence. It is deliberately not a lock: a lock that a heartbeat can hold is a way to lock an inventory by closing a laptop lid, and everything that can actually refuse a write — the content hash, the tree revision — is a check on the tree rather than on a claim.
• Nothing new becomes a file name. ?path= on /api/tree goes through the same check as /api/file/<path>: relative, below the root, no component the loader skips, YAML suffix. It is a second door into the same room and it has the same lock.
• Nothing becomes a git option. ?rev= on /api/frame reaches a git argument list, and git log --output=<file> writes a file while --upload-pack=<cmd> runs a program. A revision that begins with - is refused by name before any git process starts, on every path that takes one — the route, the timeline, netviz log and netviz diff --from alike.

The default port is 8081, one above the watch preview's, so a watch run and an editing session can be open at the same time. --port 0 lets the operating system choose one instead. --open — on by default — points the default browser at the page once the server is listening; --no-open prints the URL and leaves the browser alone, which is what you want over SSH.

Arguments

Options

Exit codes

The interface is ended by Ctrl-C, which is how the command is meant to finish. Text that does not parse is reported in the page, not by the process.

See also

• netviz edit — the same operations from the command line, and the layer every write in the browser goes through.
• netviz diff — the same overlay from the command line, over two folders, a git ref or a saved plan.
• netviz watch — the same live diagram without an editor, for a second screen.
• docs/editing.md — what an operation is, what an inverse promises, and how geometry is stored.
• docs/rendering.md — the layers and display options the header exposes, and the tooltips the info box shares its records with.
• docs/inventory-layout.md — why a folder tree means namespaces and a stream does not.
• docs/validation.md — the problems the middle pane lists.
• docs/testing.md — the headless-browser suite that drives this page, and how to run it.