Reality is the source of truth.
State files are a mirror you can edit.

End-to-end: Meraki switch ports

Meraki ports is the canonical example below. The same shape works across modules: every kind supports snapshot and diff; apply only where the module wires live writes for that kind (see each module page). YAML headers and the Action diff model are shared. See "Kinds shipping today" below for the full matrix.

Safe workflow: snapshot → edit YAML → diff (read-only, anytime) → review the panel → apply --yes in CI or confirm interactively. Destructive do commands (remove, wipe, suspend, …) require --yes as well.

1. 1 / snapshot

   Capture the truth

   $ weave meraki snapshot ports --network "Main Office"
   Saved .weave-state/meraki/acme-hq/main-office/ports.yaml  (1 switch, 24 ports)

   The file lands at .weave-state/<module>/<org-slug>/<network-slug>/<kind>.yaml. Override the root with WEAVE_STATE_DIR. Commit the folder to git — that's the whole versioning story.

2. 2 / edit

   Open the file, change what you need

   # weave state file — captured live, edit freely, then `weave apply`.
   schema: weave.state/v1
   module: meraki
   kind: ports
   scope:
     org_name: Acme HQ
     network_id: L_12345
     network_name: Main Office
   captured_at: '2026-05-15T15:02:13Z'
   
   data:
     switches:
       - serial: Q2XX-AAA-BBB
         name: sw-01
         model: MS120-24
         ports:
           - port_id: "1"
             name: Reception
             enabled: true
             type: access
             vlan: 10    # <-- bump to 20
             poeEnabled: true
           - port_id: "2"
             name: Conf-Room    # <-- rename + disable
             enabled: true
             type: access
             vlan: 10
             poeEnabled: true
           ...

   Use cases that fall out naturally: bulk port changes (find/replace), swap a switch serial for hardware migration, review a coworker's pending change as a git diff, restore last week's known-good state with git checkout.

3. 3 / diff

   See exactly what will change

   $ weave meraki diff ports --network "Main Office"
   Comparing .weave-state/meraki/acme-hq/main-office/ports.yaml against live …
   Pending changes:  +0  ~2  -0  (0 no-op)
   ~ switch-port    Q2XX-AAA-BBB port 1
       vlan:    10 → 20
   ~ switch-port    Q2XX-AAA-BBB port 2
       name:    'Conf-Room' → 'Conf-Room-Renamed'
       enabled: True → False

   Diffs are computed field-by-field — you see exactly the fields that will be touched, never a wall of unchanged YAML. diff is read-only and safe to run anytime. Run it after every snapshot to confirm nothing changed underneath you.

4. 4 / apply

   Push the changes

   $ weave meraki apply ports --network "Main Office"
   Comparing .weave-state/meraki/acme-hq/main-office/ports.yaml against live …
   ╭─ Pending changes ─────────────────────────────────────╮
   │ meraki apply ports   +0 add  ~2 change  -0 remove     │
   ╰───────────────────────────────────────────────────────╯
   ~ switch-port    Q2XX-AAA-BBB port 1
       vlan: 10 → 20
   ~ switch-port    Q2XX-AAA-BBB port 2
       name: 'Conf-Room' → 'Conf-Room-Renamed'
       enabled: True → False
   Apply these changes? [y/N]: y
   Applied meraki ports: +0 ~2 -0

   apply always runs diff first and shows a summary panel before anything hits the API. With no pending changes it prints No changes and exits. Pass --dry-run (same as diff) to preview only, or --yes / -y in CI after you have reviewed the diff. Deletes and whole-document kinds (ACL, policies) get an extra high-impact warning.

5. 5 / rollback

   Something broke? git is the rollback story.

   $ git checkout HEAD~1 .weave-state/meraki/acme-hq/main-office/ports.yaml
   $ weave meraki apply ports --network "Main Office" --yes
   Pushed 2 update(s) to Meraki.
   $ git checkout main .weave-state/    # go back to current state file

   No state engine. No terraform state ceremony. The file is the snapshot; git is the history; apply is the time machine.

Adding state kinds to a module

Each module can opt-in to as many state kinds as makes sense — 24 kinds across 23 modules ship today (see "Kinds shipping today" above). Add a new kind by writing three small functions:

# src/weave/modules/<name>/state.py
def snapshot_ports(network: str) -> tuple[dict, dict]:
    """Pull live state. Return (scope, data) for the YAML header + body."""
    ...

def diff_ports(desired: dict, live: dict) -> list[Action]:
    """Compare file vs live. Return one Action per change."""
    ...

def apply_ports(actions: list[Action]) -> None:
    """Execute the Actions against the live API."""
    ...

Then declare it on the manifest and wire three Typer commands — full example in CONTRIBUTING.md.