Graph CLIX

ss graph provides an enterprise-style, agent-friendly CLIX for graph authoring, planning, linting, and graph diffs.

Plan from a blueprint

ss graph plan --blueprint=.starsystem/harnesses/demo-harness/blueprint.yaml
ss graph plan --blueprint=.starsystem/harnesses/demo-harness/blueprint.yaml --json

plan compiles a Spacecraft-style blueprint node graph into a normalized Starsystem graph plan and prints:

• summary (nodes, edges, startNode, cyclesDetected)
• normalized nodes/edges
• structural errors (if any)

Initialize a graph

ss graph init --name=harness-topology

By default this writes:

• .starsystem/graph.yaml

You can override the path with --graph=<path>.

Add and modify nodes

ss graph node add planner --type=agent --label="Planner" role=planner
ss graph node set planner owner=platform team=\"agent-systems\"
ss graph node rm planner

Supported node types:

• agent
• gateway
• trigger
• event
• tool
• http
• code
• storage
• service
• custom

Add and remove edges

ss graph edge add planner implementer --when="mode === 'build'" --label="build path"
ss graph edge rm planner implementer

• --when stores an edge condition expression
• --label stores human-readable edge text

Validate

ss graph validate
ss graph validate --json

Validation checks:

• duplicate node ids
• invalid node ids/types
• edges referencing missing nodes

Lint

ss graph lint
ss graph lint --json

Lint focuses on quality concerns beyond schema validity, including:

• unlabeled nodes
• isolated nodes
• weak gateway/trigger wiring
• unlabeled/unconditional edges
• self-loops

Diff two graph files

ss graph diff .starsystem/graph.prev.yaml .starsystem/graph.yaml
ss graph diff .starsystem/graph.prev.yaml .starsystem/graph.yaml --json

Diff reports:

• added/removed/changed nodes
• added/removed edges
• summary counts for CI and review gates

Render (stdout-first)

render prints diagram source to stdout by default (ideal for piping to d2 or dot).

From a graph file (default .starsystem/graph.yaml):

ss graph render --format=d2
ss graph render --format=dot

From a Spacecraft blueprint (compiles the same plan as ss graph plan, then renders):

ss graph render --format=d2 --blueprint=.starsystem/harnesses/demo-harness/blueprint.yaml

Optional file output (writes the diagram to the file; prints a short confirmation line to stdout):

ss graph render --format=dot --out=.starsystem/graph.dot

Export (artifact / file)

export supports the same --format values as render (d2 or dot), and the same --blueprint vs --graph sources. Prefer render when you only need a quick preview on stdout; use export when you are writing a tracked artifact under .starsystem/ or CI output directories.

ss graph export --format=d2 --out=.starsystem/graph.d2
ss graph export --format=d2 --blueprint=.starsystem/harnesses/demo-harness/blueprint.yaml --out=.starsystem/demo-harness.d2
ss graph export --format=dot --out=.starsystem/graph.dot

Or print directly to stdout:

ss graph export --format=d2
ss graph export --format=dot