Cassian Gate v1 CLI Reference

Version: v1 / v1.x
Status: STABLE
Scope: CLI surface (commands, flags, semantics)

This document lists supported CLI commands and their semantics in v1 / v1.x.

1) Core Commands

`cassian gen <topology.yaml>`

Purpose: Generate containerlab artifacts from a topology.

input: a topology YAML filename under ./topologies or a full path
output: generated lab artifacts under labs/ (non-authoritative)

`cassian validate <topology.yaml> [--json]`

Purpose: Validate topology + scenarios without deploying containers.

Flags:

--json
Emit machine-readable JSON output (CI-friendly).

`cassian up <topology.yaml> [--reconfigure]`

Purpose: Generate and deploy a lab.

Flags:

--reconfigure
Destroy the existing lab first, then redeploy.

`cassian down <name>`

Purpose: Destroy a deployed lab by name.

Arguments:

<name> is the lab name (topology name).

`cassian cleanup --all [--yes]`

Purpose: Safely clean up Cassian Gate-owned labs found under labs/.

Flags:

--all (required)
Only targets Cassian Gate labs that have artifact dirs under labs/clab-*.
Never scans Docker globally.
--yes
Actually destroy labs listed in the plan.
Artifacts are not deleted.

Default behavior:

dry-run unless --yes

`cassian import <source> --out <dir> [--backend <name>]`

Purpose: Bootstrap an authoritative pair — a topology plus starter invariants — from committed brownfield sources, fully offline.

Arguments:

<source>
Brownfield source directory containing a committed NetBox-derived export (netbox_export.json) and rendered device configs under rendered/. This is Cassian Gate's defined input contract, not a raw NetBox API dump; see the Brownfield Importer guide.

Flags:

-o, --out <dir> (required)
Output directory for the emitted pair: an authoritative topology.yaml (with embedded scenario tests) and tests/starter_invariants.yaml.
--backend <name>
Importer backend (default: netbox). The backend seam is open for future sources; additional backends are planned but not yet available.

Behavior:

Offline and deterministic. No network or live-device access; identical inputs always produce byte-identical output.
No synthesis. Starter invariants are generated only from explicitly declared facts, never inferred or guessed.
Fail-closed. Unsupported or malformed input is rejected with exit 2 (input/artifact error; see §6) and an actionable message — the importer never emits a partial or invalid pair.

2) Exec and Inspection Helpers

`cassian exec <lab> <node> [command...]`

Purpose: Execute a command inside a container.

Arguments:

<lab>: lab name (topology name)
<node>: node name (e.g., r1)
[command...]: remainder arguments executed inside container

Behavior:

if no command is provided, opens an interactive shell

`cassian vty <lab> <node> "<vtysh command>"`

Purpose: Run a vtysh command on an FRR node.

Arguments:

<lab>: lab name
<node>: FRR node name
<vtysh command>: one string, e.g. "show bgp summary"

`cassian status <lab> [flags]`

Purpose: Show lab status (containers + optional FRR info).

Flags:

--bgp
Include show bgp summary for FRR nodes.
--bgp-verbose
Print full show bgp summary output.
--strict
Exit non-zero if any FRR peers are not Established.
--interfaces
Include ip -br a output per node.
--summary
Print a one-line summary at the end.
--json
Emit machine-readable JSON (no command echo).
--routes
Validate expected routes exist (read-only check).
--routes-verbose
Include raw show ip route output (human mode).

`cassian collect <lab>`

Purpose: Collect runtime artifacts for a lab.

Arguments:

<lab>: lab name

Notes:

This is an operational helper. The authoritative artifacts remain results.json and topology.resolved.yaml.

3) Gate Command

`cassian test <lab | topology.yaml> [flags]`

Purpose: Run declared tests and scenarios. The single positional argument accepts two forms with distinct semantics, selected by whether the value is a topology file path:

cassian test <topology.yaml> (gate mode) — when the positional ends in .yaml/.yml, runs an authoritative clean-state gate (up → test → down) using the topology name (or filename stem). This is the authoritative gate path.
cassian test <lab> (lab-test mode) — when the positional is a lab name, runs the declared tests and scenarios against an existing labs/clab-<lab>/ artifact set (no deploy/teardown). This does not perform the clean-state gate cycle.

Authority: Gate mode (<topology.yaml>) is the authoritative clean-state gate (up → test → down); lab-test mode (<lab>) runs tests against pre-existing lab artifacts. The contract remains binding in both.

Arguments:

<lab | topology.yaml>: either a lab name (e.g. three-frr-two-hosts-fw-routed, → lab-test mode) or a topology file path ending in .yaml/.yml (e.g. topologies/three-frr.yaml, → authoritative clean-state gate mode). Optional when using --two-run (then provide --two-run-topology).

Test selection flags:

--name <test-name>
Run only the test with this name.
--kind ping|tcp
Run only tests of this kind.
Note: this filter is limited to ping|tcp even though v1.x supports bgp_neighbor as an atomic test type.
--tag <tag> (repeatable)
Run only tests carrying at least one of the supplied tags (OR-union across repeats). Kind-agnostic.
Non-matching declared tests are recorded explicitly as not_executed (never silently dropped); the gate verdict is computed from executed tests only. A --tag selection matching nothing hard-fails, like --name/--kind zero-match.
--keep-going
Run all tests even if one fails (still exits non-zero if any fail).

Output flags:

--json
Print results.json to stdout in addition to writing the file.

Scenario flags:

--scenario <id>
Run only this scenario ID (scenarios[*].id).
--all-scenarios
Run all scenarios after steady-state tests.
--scenario-verbose
Print each scenario step as it runs (human-only; does not change artifacts).

Convergence control:

--precheck-controlplane
Run global control-plane prechecks (e.g., BGP wait) before executing scenarios.
Default: off when --scenario / --all-scenarios is used.

Listing:

--list-scenarios
List scenarios from labs/clab-<lab>/topology.resolved.yaml (no deploy/execute).

State capture flags:

--state-capture {none, pre, post, both}
When to run state-capture probes. none disables (default), pre runs probes before tests, post runs after, both runs at both points. Captures are written as non-authoritative supporting evidence and never change verdicts, exit codes, or authoritative artifacts.
--state-profile <name> (repeatable)
Select which built-in state-capture profile(s) to run. Repeat the flag to run multiple profiles in one invocation. Required when --state-capture is not none. The built-in profiles are:
- frr-routing-basic — IPv4 and IPv6 routing tables from FRR zebra (show ip route json, show ipv6 route json).
- frr-bgp-basic — BGP control-plane state from FRR bgpd (summary, neighbors, IPv4-unicast prefixes).
- frr-ospf-basic — OSPFv2 state from FRR ospfd (neighbors, interfaces, LSA database). Requires the topology to declare an ospf: block.
- frr-interfaces-basic — interface admin/operational state on FRR nodes via Linux iproute2 ip -j link show and ip -j addr show (not vtysh). Pairs naturally with the interface_state invariant.
- frr-comprehensive — aggregate of the four FRR profiles above (10 commands). OSPF commands included unconditionally; produce empty/non-fatal output on non-OSPF topologies.
- linux-net-basic — basic interface, route, and neighbor state on Linux hosts (ip addr, ip link, ip route, ip neigh).
- linux-sockets-basic — listening TCP/UDP sockets on Linux hosts (ss -tulpn).
- nft-ruleset-basic — nftables ruleset on nft-fw firewall nodes (nft list ruleset).
- linux-forwarding-basic — IP forwarding and rp_filter sysctls on nft-fw nodes (net.ipv4.ip_forward, net.ipv4.conf.all.rp_filter, net.ipv4.conf.default.rp_filter).

Full per-profile descriptions live in contrib/state-profiles/README.md.

4) One-shot Workflow (Non-authoritative)

`cassian run <topology.yaml> [flags]`

Purpose: Ephemeral workflow: up → test → collect → down.

This is explicitly non-authoritative and primarily for exploration / convenience.

Flags:

--reconfigure
Destroy the existing lab first, then redeploy.
--keep
Do not destroy the lab at the end (useful for debugging failures).
--destroy-always
Attempt to destroy the lab even if up/test/collect fails.
--no-collect
Skip collect (faster, but no artifacts).

5) Assistive AI (Advisory Only)

`cassian ai`

Purpose: Optional advisory AI entrypoint.

Behavior:

explicitly invoked by the operator
advisory only
non-authoritative
never changes verdicts, exit codes, lifecycle execution, or authoritative artifacts

Notes:

shipped AI behavior must be described only through the cassian ai entrypoint
AI guidance remains outside the authority chain
absence or unavailability of AI does not weaken deterministic engine behavior

6) Exit Code Semantics

0
Success.
2
Usage / input / artifact error (not a gate failure).
non-zero (other)
Hard execution failure (deploy/provision/runtime failure), or strict status failure.

End of Cassian Gate v1 CLI Reference