fcli

What an SR Linux fabric looks like, what is wrong with it, and what changed, straight from gNMI.

This is a ground-up rewrite of fcli. It runs on asyncio throughout, uses no Nornir and makes no blocking gNMI calls.

uv tool install 'fcling[server,mcp,ai]'                    # the `fcling` command, from PyPI
docker run --rm --network host -v "$PWD:/work" ghcr.io/wdesmedt/fcling -t lab.clab.yml bgp-peers

Or from a checkout:

uv sync
uv run fcling -t lab.clab.yml bgp-peers
uv run fcling -t lab.clab.yml -i role=leaf -o json subif -f oper=down
uv run fcling -c inventory.yml sys-info
uv run fcling -t lab.clab.yml ipv4-rib -a 10.1.3.99          # longest-prefix match
uv run fcling -t lab.clab.yml bgp-rib -r evpn -t 5 -d        # with the detail columns
uv run fcling -t lab.clab.yml ifstats -s 2 -f oper=up        # rates over 2 s

With the engine running, the same commands answer instantly from what it streams, and can look back:

uv sync --extra server
uv run fcling -t lab.clab.yml serve                          # streams every node, keeps history
export FCLI_SERVER=http://127.0.0.1:8765
uv run fcling bgp-peers                                      # live, from the engine
uv run fcling bgp-peers --at 14:02                           # as it was then
uv run fcling history --since 1h -r bgp-peers --follow       # what changed, which commit did it, and keeps watching

What is wrong, and what changed:

uv run fcling checks                          # every finding, check by check
uv run fcling incidents -v                    # grouped by root cause, worst first
uv run fcling incidents --at 14:02            # what was wrong then
uv run fcling baseline pre-change -m "before the MTU change"
uv run fcling drift pre-change                # what came, went and changed since

Ask, or let your own AI client ask. Both get the same 8 read-only tools: status, reports, incidents, checks, history, drift and baselines.

uv sync --extra server --extra mcp --extra ai
uv run fcling ask "what is wrong, and what changed just before?"        # the first provider with a key
uv run fcling ask --provider openai --effort low "is BGP healthy?"
claude mcp add --transport http fcli http://127.0.0.1:8765/mcp        # MCP over HTTP from `fcling serve`
claude mcp add fcli -- fcling --server http://127.0.0.1:8765 mcp        # or over stdio

Questions across the whole fabric, and its shape:

uv run fcling -t lab.clab.yml where 10.1.3.13                        # every place that knows an IP or MAC
uv run fcling -t lab.clab.yml path leaf1 10.1.3.13 --ni ipvrf-1      # hop by hop, over ECMP and VXLAN
uv run fcling -t lab.clab.yml service macvrf-102                     # one service on every node, and what disagrees
uv run fcling -t lab.clab.yml endpoints                              # every attached host
uv run fcling -t lab.clab.yml topology                               # tiers, cables, clients, segments

checks and incidents work without a server too: one-shot from the nodes, or from the local history with --at. They exit 1 when there is an error, so they can gate a pipeline.

Reports: sys-info, config-commits, lldp, subif, lag, ifstats, ni, bgp-peers, bgp-rib, ipv4-rib, ipv6-rib, tunnel-table, static-routes, routing-pol, mac, arp, nd, irb, es, es-dest, vxlan, bfd, isis, ospf, resources, components, transceivers, services, bridge-domains, routers. Each is a pure function from gNMI paths to typed records.

Documentation

Architecture

inventory ──► collect ──► gNMI Get (one per datatype, all nodes at once)
                              │
                              ▼
                        Tree (per node)  ◄── later: gNMI Subscribe, same tree
                              │
                              ▼
            report: pure function Tree → typed records
                              │
                              ▼
                 render: table · json · yaml · csv

Because a report only declares paths, the same definition can be fed by a one-shot Get (CLI), by a STREAM subscription (server) or by a recording (tests). Its subscription plan is static data that can be checked without a device.

Static inventory

defaults:
  username: admin
  password: NokiaSrl1!
  tls: {ca_file: ca.pem}      # or {skip_verify: true} / {insecure: true}
nodes:
  leaf1: {address: 10.0.0.11, labels: {role: leaf}}
  spine1: {address: 10.0.0.21, labels: {role: spine}}

Tests

make test lint

tests/fixtures/releases holds real gNMI recordings from the original fcli for SR Linux 25.3 to 26.7. test_release_matrix.py replays them through the new reports and requires row-for-row equality with what the original rendered. fake_gnmi.py is an in-process gNMI target, so the client, TLS, the collector and the CLI are tested without a lab.

test_engine.py and test_server.py stream from that same fake target. They cover the initial sync, refused paths, live changes and deletes, history and state_at, and SSE replay over a real uvicorn.

The gNMI stubs are generated from the openconfig protos (make proto) and committed.

Roadmap

1. Inventory, async gNMI client, node tree, recorded fixtures
2. Declared-path reports with typed records, and a one-shot CLI. 27 reports are ported, and every one with recorded data matches the original row for row. services, bridge-domains, routers and endpoints move to phase 6: the old getters built display strings and web-UI tiles, and these should be typed records over ni, irb, es, mac and arp/nd.
3. Long-running engine: subscriptions planned from the declared paths, record-level changes in SQLite, HTTP/SSE, plus fcling serve, --server, --at and history. On both labs the engine's live records match a one-shot run for every report.
4. Checks, incident correlation, timeline and baselines. Findings live in the engine and are kept as history. Incidents carry "since". --at works for findings and incidents, baselines and drift work through the store, and history is attributed to commits. On both labs the engine's findings match a one-shot run.
5. MCP served from the engine, and the in-app agent on the same tools: /mcp, fcling mcp, /api/chat and fcling ask. All of them use the same tools over one Service, with Claude, OpenAI or Grok as the model.
6. Lenses and topology: where, path, service, endpoints and topology, from the nodes, the engine or the history. They are served over /api/lenses and /api/topology, and five more tools use them. services, bridge-domains and routers are typed reports. endpoints became a lens, because placing a host needs every node's tables.
7. Web UI, served by fcling serve with no build step: a navigation panel; topology, incidents and history; the lenses, with path and where drawn on the topology; every report as a live table; and the agent beside any view. All of it works live or at an instant.