3. See it

Draw the board, and get a picture of a netlist that has no drawing.

A finding names a net. Nobody thinks about a board as a list of net names, so at some point you need a picture. There are two different situations here and they need different answers.

If your design carries its own geometry, the tool draws that geometry, and the picture is the one your CAD tool would draw. If your design is a netlist, there is no geometry to draw, because a netlist records what is connected and never records where anything sits. In that case the tool computes a layout from the connections.

The tutorial board is the second case. gateway.edn is an EDIF netlist.

Draw a netlist ¶

$ agni render designs/gateway/gateway.edn --layout layered -o gateway.svg
note: reading gateway.edn with sheets from gateway.kicad_sch and board geometry from gateway.kicad_pcb (declared by designs/gateway/design.yaml). Pass --as-named for the file alone.
layout "layered": 19 nodes, 15 nets, 56 segments, 95 crossings, edge length 20826
wrote gateway.svg (sheet "netlist graph", 19 placements, 15 wires)

The line it prints is a quality report on the drawing, not on your board. crossings counts wires that cross each other, and crossings are what mainly make a generated schematic hard to follow.

This is a drawing of your netlist, not a reproduction of your schematic. Parts sit where the layout algorithm put them. It is for following connectivity, not for review of the drawing itself.

Compare it against the faithful drawing further down. Same board, same nets, and a completely different picture, because one was drawn by a person and the other was solved for.

Pick a layout ¶

There are five, and which one reads best depends entirely on the board. Rather than guess:

$ agni render designs/gateway/gateway.edn --compare
layout      nodes  nets  segments  crossings  bends  edge-length  stress  truth-residual
force       19     15    56        43         0      9052         0.346   0.997
grid        19     15    56        133        0      7798         0.486   0.978
layered     19     15    56        95         0      20826        0.582   0.960
orthogonal  19     15    84        104        28     9200         0.457   0.961
stress      19     15    56        73         0      7218         0.457   0.961

For this board force has by far the fewest crossings and grid is the worst by that measure, while stress draws the most compact picture by edge length. orthogonal is the only one that bends wires into right angles, which is what a schematic normally looks like, at the cost of more segments and more crossings.

Lower stress means the drawn distances better match how far apart things actually are in the connection graph. There is no single winner. Render the two or three that score well and look at them.

Faithful geometry ¶

When the design does carry geometry, drop --layout and you get the design’s own drawing. The tutorial board ships a KiCad view of itself for exactly this:

$ agni render designs/gateway/gateway.kicad_sch --symbol-path designs/gateway/symbols -o gateway.svg
wrote gateway.svg (sheet "Sample Board", 19 placements, 56 wires)

That is placements and wires read out of the file rather than computed, so the result is the drawing somebody drew. Faithful is the default. --layout is what you reach for when there is nothing to be faithful to.

The same board, twice ¶

gateway.edn and gateway.kicad_sch are two views of one design, which raises the obvious question of whether they still agree. Ask directly:

$ agni diff designs/gateway/gateway.edn designs/gateway/gateway.kicad_sch \
  --symbol-path designs/gateway/symbols
diff designs/gateway/gateway.edn -> designs/gateway/gateway.kicad_sch

Components: +0  -0  ~0
Nets:       new 0  deleted 0  renamed 0  hard 0  soft 0

Zero net changes. The two readers converged on the same netlist, and the whole engine rests on that premise: analysis runs over one internal representation, so the format you started from stops mattering once the file is read.

This is also the practical way to check a CAD migration. Export from the old tool and the new one, diff the two, and an empty net delta is real evidence the design survived the move.

In the browser ¶

agni open serves one design and prints the URL that shows it:

agni open designs/gateway/gateway.edn

It picks a free port on loopback, so it will not collide with anything you already have running, and it serves only this design and the project around it. The URL it prints goes straight to the board rather than to a file browser.

It needs the viewer’s built assets, and it does not carry them. From a repo checkout they sit in ./web after make ui, which is the default, and that is why every other command on this page works here and this one may not. Anywhere else, point at them once:

agni open designs/gateway/gateway.edn --web-dir /path/to/web

AGNI_WEB_DIR and a web_dir: line in agni.yaml do the same thing without repeating the flag, and the error names all three if you get it wrong.

The viewer pans and zooms, and its panels run the same checks the CLI runs, over the same catalog, so the findings you saw in rung 2 appear against the drawing rather than as a list. Later rungs add tiers to that catalog, and the viewer picks them up the same way the CLI does.

agni open also prints a ready-made agni check command pointed at the server it just started, which is what rung 11 uses to turn a report’s subjects into links.

For several designs at once, or for a server other people reach, agni serve takes a mount per folder. It has to be told where the viewer’s own assets are, which agni open works out for itself.

Next ¶

Your names, where the tool stops being generic and starts knowing your team’s conventions.