Home > Reading the node graph

< Previous: Boolean commands | Next: Keyboard shortcuts >

CLI

Reading the node graph

Six commands reach the node editor rather than the drawing. They let you read a node graph, change one parameter, and re-run it. They do not let you build one.

[!IMPORTANT] Under construction. The CLI is being built, and this page describes work in progress. What it is called, what it can do, and how it behaves are all still moving. Nothing here is a promise about the finished feature.

What these six can do

Four of them only look:

graph summary

A survey of the whole node graph.

graph wires

Every connection in it.

graph node \
  --ref "Polygon 1"

One node in full.

graph trace \
  --ref "Polygon 1" \
  --depth 2

Walks back from one node through everything that feeds it, as far back as --depth says.

Two of them change the document:

graph set-param \
  --node "Polygon 1" \
  --key "sides" \
  --value 8

Sets one parameter on one node. The key is checked against the keys that node really has, so a misspelled key is refused rather than accepted and quietly ignored.

graph evaluate

Runs the node graph and says whether work is still pending.

What they cannot do

There is no command to add a node, wire two together, unwire them, or delete one. A node graph has to be built in the node editor, by hand. This is not a case of waiting for a release: those commands are not there, and whether they ever arrive has not been decided.

So the shape of what you can do from the command line is: build the graph yourself, then drive it.

Naming a node

Three things work as a reference, wherever a command takes --ref or --node:

• its id
• its label, if it has one
• its type, when only one node in the graph is of that type

An ambiguous reference is refused rather than guessed at, and the refusal lists the candidates, so you can see what you have to choose between and name one of them exactly.

Changing a parameter, then seeing the result

graph set-param sets the value. It does not re-run anything by itself. Run graph evaluate after it to push the change through the graph:

graph set-param \
  --node "Polygon 1" \
  --key "sides" \
  --value 8

graph evaluate

Each of those two is one undo step, because each changes the document. The four reading commands make no undo step at all.

[!CAUTION] Read the caution on the CLI server page first. With both the modeling window and the node editor open, changes made from outside the normal editing path can be lost while the two windows reconcile. That is being fixed, and until it is, it bears on anything you do here.

Related

• How the node graph works: what a node graph is, in the window.
• Adding & connecting nodes: how one gets built, which is by hand.
• CLI commands: the commands, what each takes, and what it does.
• CLI server: the lock, the transaction, and the caution above.

< Previous: Boolean commands | Next: Keyboard shortcuts >