Getting started

From nothing to a first checked design in a few minutes.

This page gets you from nothing to a first checked design in a few minutes. It assumes the vocabulary from Concepts (what a finding, a tier, and provenance mean). If a word here is unfamiliar, that page is the glossary.

Install

If you have a Go toolchain, install the CLI straight onto your PATH:

go install github.com/panyam/agni/cmd/agni@latest

Pin a released version rather than @latest for anything whose output you keep. A check report is only reproducible if you can say which build produced it, and @latest moves under you between runs. Releases are plain git tags, so the tag list is the version list.

Or build from a clone, which also gives you the sample designs used below:

git clone https://github.com/panyam/agni
cd agni
make install      # installs `agni` into your GOBIN
# or: make agni  # builds ./bin/agni without installing

Confirm it runs:

agni --help

Your first check

agni check runs the rule catalog over one design and prints what it found. Point it at your own schematic or board, or at a sample from the clone. Here is a sample that deliberately trips several rules:

$ agni check cmd/agni/testdata/conformance/showcase.fires.kicad_pro
findings by rule:
  bulk-cap               2
  decoupling-present     2
  esd-protection         2
  i2c-pull-up            1
  input-protection       1
  reverse-blocking-absent 1
  test-point-coverage    2

first 11:
  [warning] bulk-cap: +3V3 (power rail has no bulk capacitor)
  [warning] bulk-cap: VBUS (power rail has no bulk capacitor)
  [warning] decoupling-present: +3V3 (power rail has no decoupling capacitor)
  [warning] decoupling-present: VBUS (power rail has no decoupling capacitor)
  [info] esd-protection: USB_D+ (externally-exposed signal net has no ESD protection)
  [info] esd-protection: USB_D- (externally-exposed signal net has no ESD protection)
  [error] i2c-pull-up: SCL (I2C net has no pull-up resistor to a rail)
  [warning] input-protection: VBUS (connector feeds a power input with no fuse or TVS in the path)
  [warning] reverse-blocking-absent: VBUS (connector feeds a power input with no reverse-blocking element in the path)
  [info] test-point-coverage: GND (rail carries no test point; bring-up and factory test cannot probe it)
  [info] test-point-coverage: VBUS (rail carries no test point; bring-up and factory test cannot probe it)

11 finding(s) total
152 subject(s) considered by 26 rule(s), 2 not considered (--verdicts for the detail)

Read a finding as three parts: the severity (error / warning / info), the rule that fired (i2c-pull-up), and the subject it fired on (the net SCL), with a plain-language reason in parentheses. Each finding also carries its provenance: run --format json (below) to see exactly which net or pin, and for datasheet rules which page and table, the finding came from.

Severity is a policy signal, not a measure of certainty. An error is something you almost certainly must fix (an I2C bus with no pull-up will not communicate). A warning sits between them. A rail with no decoupling capacitor often works on the bench and fails intermittently in the field. info is a note worth a look.

A clean run, and why “no findings” has a number in it

Run the passing twin of that board:

$ agni check cmd/agni/testdata/conformance/showcase.passes.kicad_pro
no findings (83 rule(s) run)
193 subject(s) considered by 24 rule(s) (--verdicts for the detail)

The 81 rule(s) run is the important half. It tells you the check actually exercised 81 rules and none fired, rather than staying quiet because it had nothing to work with. This is the “silence is not a pass” idea from Concepts: a real all-clear names how many rules ran. If you load only a schematic and no board file, the copper rules simply do not appear in that count, because their tier is empty.

The second line is the narrower claim underneath it. 81 rules ran, and 22 of them reached a subject to say something about, over 189 subjects between them. A rule that ran and found nothing to look at is not evidence about this board.

Sanity-check the read first

Before trusting any finding, confirm the tool read your design the way you expect. agni stats summarizes what it ingested:

$ agni stats cmd/agni/testdata/conformance/showcase.fires.kicad_pro
design:              Showcase Board (fires)
source format:       kicad-sch
libraries:           2
components:          13 (unique ref_des)
sections:            13 (source instances)
multi-section:       0 (one ref_des, several sections)
nets:                11

If the component or net counts look wrong, the findings downstream will too. Fix the read (often a missing symbol library, see the --symbol-path note in the CLI reference) before chasing a surprising finding.

Other output formats

The default text form is a summary. Two others are useful early:

  • agni check <file> --format markdown renders a severity-organized report, worst first, for pasting into a review.
  • agni check <file> --format json emits one object per finding with its full subject and provenance, for tooling.

Gate a build on it

--fail-on makes check exit non-zero when anything at or above a severity is present, so it can sit in CI:

agni check <file> --fail-on error   # fails the build only on errors

Stop passing flags

Everything above addresses a single file, and the flags pile up as you turn things on: your naming conventions, your interface profiles, your parameter corpus, your checklist. A project is where those live instead, declared once beside the design.

agni start builds one from a design you already have, here the same board this page has been checking:

$ agni start cmd/agni/testdata/conformance/showcase.fires.kicad_pro ./showcase-review
Created project "showcase-review".

  showcase-review/project.yaml
  showcase-review/conventions.yaml        (stub — your team's naming vocabulary)
  showcase-review/review.yaml             (seeded from the shipped catalog — edit it)
  showcase-review/designs/showcase.fires/design.yaml
  showcase-review/designs/showcase.fires/showcase.fires.kicad_pro   (copied)
  showcase-review/designs/showcase.fires/showcase.fires.kicad_sch   (copied, declared as a companion view)

The project owns these copies. Edits to the original files do not reach it.

Next:
  agni check showcase-review/designs/showcase.fires
  agni review showcase-review/designs/showcase.fires

From then on the commands take a design and nothing else, because the project answers the rest, which is what the two lines under Next: are.

The design is copied into the project, which now owns its copy, so edits to the original do not reach it, and a companion view the design declares is copied beside it. The generated review.yaml is a starting point seeded from the shipped catalog rather than a finished checklist; Write your checklist is about turning it into your team’s.

Where to go next

  • Checks and reports: narrow to one rule or category, read the full report, and follow a finding’s provenance.
  • Datasheets: add a parameter set so checks can compare your design against a part’s real limits.
  • CLI reference: the full command and flag surface.