cli commands

Home > CLI commands

< Previous: CLI server | Next: Keyboard shortcuts >

CLI

CLI commands

Every command you can write for the CLI server, what each one takes, and what it does.

Important

Under construction. The CLI server is being built, and this list is being built with it. Commands may be added, renamed, or changed. Nothing here is a promise about the finished feature.

How a command is written

A command is a verb and its parameters. Write each parameter on its own line, named, with a trailing backslash joining them:

model glider \
  --host "Bisector A" \
  --at 20,34 \
  --name "s1"

• Always name the parameter. Never rely on argument order: a reader cannot tell order from looking.
• Names are double-quoted, and a list takes commas: --members "Bisector A","Bisector B".
• A coordinate is written x,y, as one value.
• A number or a true/false may be written as text, so "15", "true" and "no" all read correctly. A script has only text to send.
• # starts a comment, whole-line or trailing.
• Commands live in a plain text file with a .locuscli extension, one command per line.
• Commands run in order, as one undo step. A whole file commits together, and any failure rolls the whole thing back, so there is nothing to begin or commit by hand.

Parameter types

Every parameter below carries its type in brackets.

Type	What you pass
point	The name of a point already in the drawing. Not a coordinate.
object	The name of any object.
circle	The name of a circle; a few commands also take an arc, and say so.
segment, line or ray	The name of one of those three. Nothing else can act as a direction, an edge or an axis.
group	The name of a group that already exists.
node	A node in the node graph, by id, label or type.
list of objects	Names separated by commas.
coordinate	A pair of numbers written x,y, in document units. This is the one place a raw position is passed.
number / true or false / text	Plain values.

Warning

--side does not mean the same thing everywhere. model tangent-point-circle, model tangent-circle-circle and model bisector-angle-edges take 0 or 1, because the engine reads those as a flag. model circle-center-tangent takes 1 or -1. Each refuses the other's values rather than quietly rounding, which is what keeps both choices reachable.

Caution

Ten commands here are written but not yet tested. They are marked Not tested yet in the table. They typecheck and nothing else regressed, but no test exercises them, so treat them as untried rather than as working.

Reading the tables

• Parameters in bold are required. The rest are optional.
• --name is optional everywhere it appears. Give one and the new object carries it in the Layers panel.
• One form, one entry. Where a command can be written two ways, each way has its own row with its own required set.

Reading the drawing

None of these change anything.

Command	Parameters	What it does
model summary	none	A survey of the drawing. Its hidden count now follows ownership, so a member of a hidden group counts as hidden.
model find	--kind [text] --name [text] --in [text] --style [text] --visible [true or false] --limit [number] --fields [list of text]	Searches. Each flag narrows the result. --visible follows ownership too, so hiding a group hides its members from this filter.
model get	--ref [object]	One object in full. It also names hiddenBy, the nearest owner hiding it, or nothing when the object's own flag is the one that is off.
model check	none	A consistency check over the whole drawing.

Points

All of these change the document.

Command	Parameters	What it does
model point	--at [coordinate] --name [text]	Places a free point at a position.
model glider	--host [object] --at [coordinate] --name [text]	A point pinned to a host curve and free to slide along it. The coordinate only says where to start: the point lands at the nearest spot on the host.
model intersect	--a [object] --b [object] --near [coordinate] --name [text]	The crossing of two objects. --near is a hint saying which crossing you meant; the point itself is exact and remembers its branch, so it survives a drag.
model intersect-all	--members [list of objects] --name [text]	Not tested yet. Every crossing among a set of objects, rather than one pair. Crossings that already had a point are reported as existing rather than duplicated.
model move-point	--point [point] --to [coordinate]	Moves a free point. It says which reason it refuses for: locked, managed by the node graph, or a point whose position is computed rather than stored.
model midpoint-two-points	--a [point] --b [point] --name [text]	Not tested yet. The midpoint of two points. Bound to the points.
model midpoint-segment	--of [segment] --name [text]	Not tested yet. The midpoint of a segment. Bound to the segment, so it follows if the segment is redefined.
model divide-two-points	--a [point] --b [point] --parts [number]	Not tested yet. Divides the span between two points into equal pieces. --parts is how many pieces, so it makes one fewer points than that.
model divide-segment	--of [segment] --parts [number]	Not tested yet. Divides a segment the same way.
model divide-arc	--of [arc] --parts [number]	Not tested yet. Divides an arc the same way. The old divide refused an arc outright.

Lines and rays

All of these change the document.

Command	Parameters	What it does
model segment	--from [point] --to [point] --name [text]	A segment between two points.
model line-through-points	--from [point] --to [point] --name [text]	An infinite line through two points.
model ray	--from [point] --through [point] --name [text]	A ray from one point through another.
model bisector-two-points	--from [point] --to [point] --name [text]	The perpendicular bisector of two points, bound to the points.
model bisector-segment	--of [segment] --name [text]	Not tested yet. The perpendicular bisector of a segment, bound to the segment. A different construction from the two-point form, not a convenience.
model bisector-angle	--vertex [point] --arm1 [point] --arm2 [point] --name [text]	The bisector of the angle at the vertex, from three points.
model bisector-angle-edges	--edge1 [segment, line or ray] --edge2 [segment, line or ray] --side [0 or 1] --name [text]	Not tested yet. The bisector of the angle between two crossing edges. Two bisectors exist, so --side picks, and it reads as a flag: 0 or 1.
model line-perpendicular	--base [segment, line or ray] --through [point] --name [text]	Perpendicular to the base, through a point.
model line-parallel	--base [segment, line or ray] --through [point] --name [text]	Parallel to the base, through a point.

Circles, arcs and ellipses

All of these change the document.

Command	Parameters	What it does
model circle-center-point	--center [point] --through [point] --name [text]	A circle on a center, through a point.
model circle-3-points	--a [point] --b [point] --c [point] --name [text]	The circle through three points.
model circle-center-radius	--center [point] --radiusOf [object] --name [text]	A circle whose radius is taken from another object and keeps tracking it: change the source and the circle follows. Only a circle, arc or segment has a size to lend.
model circle-center-tangent	--center [point] --target [object] --side [1 or -1] --name [text]	A circle on a center, tangent to a target. Two satisfy it, one each side, and --side picks.
model arc	--center [point] --start [point] --end [point] --ccw [true or false] --name [text]	An arc on a center, from one point to another. --ccw decides which arc you get rather than only its orientation. Counter-clockwise by default.
model arc-to-object	--center [point] --start [point] --to [object] --near [coordinate] --ccw [true or false] --name [text]	Not tested yet. An arc that runs until it meets another object, building and hiding its own defining circle, so the far end tracks that object rather than sitting where a point was placed by eye.
model ellipse	--center [point] --major [point] --minor [point] --name [text]	An ellipse from its two axis points.
model ellipse-arc	--center [point] --major [point] --minor [point] --start [point] --end [point] --ccw [true or false] --name [text]	Part of an ellipse. --ccw works as it does for an arc.
model tangent-point-circle	--from [point] --circle [circle] --near [coordinate] --name [text]	A tangent from a point to a circle, taking the one nearest a coordinate.
model tangent-point-circle	--from [point] --circle [circle] --side [0 or 1] --name [text]	The same tangent, picked by side instead. Two exist, so one of these two forms is required: with neither it refuses rather than taking the first.
model tangent-circle-circle	--a [circle] --b [circle] --near [coordinate] --name [text]	A tangent to two circles, taking the one nearest a coordinate.
model tangent-circle-circle	--a [circle] --b [circle] --inner [true or false] --side [0 or 1] --name [text]	The same, picked by --inner plus --side. Four common tangents exist, so one of these two forms is required.

Straightedge and compass

Both change the document.

Command	Parameters	What it does
model tick	--host [line] --at [point] --len [number] --name [text]	The straightedge form. A short segment collinear with the line host, centered on the point you name. It lies along its host, not across it. 4 mm by default, from the same preference the Straightedge tool reads, and --len overrides it.
model tick	--host [circle] --at [point] --len [number] --name [text]	The compass form. A short arc of the circle host, centered on the point you name. The host kind is what picks the form, so it is one command rather than two.
model strike	--host [line] --from [point] --to [point] --name [text]	The straightedge form. The piece of the line you actually drew. Both ends are points on the host, so it follows the construction when a parent point moves.
model strike	--host [circle] --from [point] --to [point] --name [text]	The compass form. The arc you actually drew. It takes the host circle's own center, so its radius is the compass opening and there is nothing to keep in sync.

Polygons and rectangles

All of these change the document.

Command	Parameters	What it does
model rect-corner-corner	--from [point] --to [point] --name [text]	From two diagonal corners, and it refuses two on one edge. The other two corners are derived, as the window's own tool makes them, so they cannot be moved directly.
model rect-edge-width	--from [point] --to [point] --width [number] --name [text]	One edge from the first point to the second, then a width square to it, so this one is not axis-aligned. A negative width puts it on the other side.
model square	--from [point] --to [point] --name [text]	A square on one edge.
model polygon	--from [point] --to [point] --sides [number] --mode [text] --name [text]	--mode says what the two points mean: edge (they are one side), vertex (the first is the center and the second a corner), or midpoint (the first is the center and the second an edge middle). Defaults to edge, and any other value is refused.

Regions and booleans

All of these change the document.

Command	Parameters	What it does
model region-from-edges	--members [list of segments or arcs] --name [text]	A region from edges that close. Too few edges and edges that do not close are told apart, rather than both reading as one failure.
model region-from-points	--members [list of 3 or more points] --name [text]	A region from points. It makes its own boundary segments rather than reusing one already running between two of them, so adjacent tiles stay independent.
model region-auto	--members [list of objects]	Finds the regions enclosed by what you give it. The one command that makes many objects at once, so it answers with a list, plus the inputs it skipped. An input enclosing nothing is not an error.
model region-union	--members [list of objects] --name [text]	The union. A closed curve counts as a boundary, so circles, ellipses, traced regions and earlier booleans all qualify.
model region-intersect	--members [list of objects] --name [text]	The overlap. Not to be confused with model intersect, which makes points where things cross.
model region-difference	--members [list of objects] --name [text]	The first member with the rest taken out of it, so the order of the list is what decides the result.
model region-split	--members [list of objects] --name [text]	Divides them against each other. Unlike the other three it answers with a group of faces rather than one shape.

Dimensions

All of these change the document.

Command	Parameters	What it does
model dimension-linear-points	--a [point] --b [point] --offset [number] --name [text]	Calls out the distance between two points. Nothing is built between them. --offset is how far off that line the dimension sits, and its sign puts it on one side or the other.
model dimension-radius-points	--center [point] --rim [point] --offset [number] --diameter [true or false] --leaderDist [number] --name [text]	A radius called out from two loose points. --diameter shows it as a diameter instead.
model dimension-radius-circle	--target [circle or arc] --offset [number] --diameter [true or false] --leaderDist [number] --name [text]	Reads the radius off a circle or arc that is already there and follows it, so changing the circle changes the dimension. The points form cannot do that.
model dimension-angle-points	--vertex [point] --arm1 [point] --arm2 [point] --offset [number] --name [text]	The angle at a vertex, between the directions of two arm points.
model dimension-angle-edges	--edge1 [segment, line or ray] --edge2 [segment, line or ray] --offset [number] --name [text]	Not tested yet. The angle between two edges, which is the other half of what the window's own tool offers.

Labels

Changes the document.

Command	Parameters	What it does
model label	--from [point] --to [point] --text [text] --size [number] --name [text]	A text box on two corner points. The corners are borrowed, not owned, so deleting the label leaves them and anything built on them. Two points in line are refused by name, since a box with no width or height could not be seen or picked. Empty text is allowed, as it is in the window.

Changing what is there

All of these change the document.

Command	Parameters	What it does
model rename	--ref [object] --name [text]	Renames one object.
model hide	--targets [list of objects]	Hides them. Hiding a group hides everything inside it, which is how a construction puts its scaffolding away. Showing one member of a hidden group does not reveal it, and the answer says so.
model show	--targets [list of objects]	Shows them again.
model delete	--targets [list of objects]	Deletes them, and reports every cascaded dependent by name rather than a count. Every target is resolved before anything is removed, so a bad name halfway down a list leaves the drawing whole.
model group	--members [list of objects] --name [text]	Makes a new group. An object has one parent, so grouping moves it out of whatever group it was in, and it refuses a group together with something already inside it rather than flattening that nesting.
model group-add	--group [group] --targets [list of objects]	Moves objects into a group that already exists. A group that is not already there is refused rather than quietly becoming a second group of that name.
model mirror	--axis [segment, line or ray] --targets [list of objects]	Reflects every target across one axis in a single call, sharing one map of points, so a corner used by two targets is reflected once and reused. It cannot mirror a perpendicular, a parallel or either kind of tangent line, and says so up front.

The node graph

Reading, plus one write. A script can read a node graph and change a parameter; it cannot build one.

Command	Parameters	What it does
graph summary	none	A survey of the node graph.
graph wires	none	Every connection in the node graph.
graph node	--ref [node]	One node in full. The reference can be an id, a label or a type.
graph trace	--ref [node] --depth [number]	Walks back from one node through everything that feeds it.
graph set-param	--node [node] --key [text] --value [whatever that parameter takes]	Sets one parameter on one node. The key is checked against the keys that node really has, and an unknown one is refused rather than accepted and ignored.
graph evaluate	none	Runs the node graph, and says whether work is still pending.

What you cannot write yet

• Making a document. Use New in the window.
• Saving. Not wired up from a script yet; use Save in the window.
• Building a node graph. A script can read one and set a parameter, but adding nodes and wiring them has no commands and is not started.

What is not coming

These are settled, not pending, so there is nothing to wait for.

• Fill and Paint are window features. Choosing a color and clicking an area is the whole task.
• Tangent Circle stays out: one set of references can have up to six answers, and two of them can share a contact signature, so there is no way to name which one you meant. Build it the Euclidean way and hide the scaffolding.

Note

How much of the window this covers is not known. Of the modeling tools, 39 of 42 have commands and 3 are deliberately out. But the command palette also holds 33 entries that are commands rather than tools, and those have never been audited, so the real figure is lower than any single number here would suggest.

< Previous: CLI server | Next: Keyboard shortcuts >