cli server

Home > CLI server

< Previous: Language & i18n | Next: CLI commands >

CLI

CLI server

CLI is short for command line interface. It lets a program outside Locus read and change the document you have open.

Important

Under construction. The CLI server 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 it is

The CLI server lets a separate program work on the drawing you have open, with your unsaved changes on screen, rather than on a file on disk. It is how a script builds a construction step by step, or reads a pattern back to check it.

It listens on a local socket on your own machine, not on a network port. A web page you have open cannot reach it.

Turning it on

It is off until you turn it on, and it does not stay on by itself between runs. The control is in Settings, under General.

Staying in control

This is the part worth reading, because it is what makes the feature safe to leave on.

Your drawing is never held hostage. While a program is working, the window takes a soft lock, and the lock gives way to you:

• Your first edit cancels it. The work is rolled back before your edit lands, so your change is never built on top of something that is about to disappear.
• It gives up on its own if the program stops talking, and after a time limit. The limit is 30 seconds by default and can be raised to at most 5 minutes.
• A rollback never undoes your own work. Only what the program made is taken back.

Changes arrive as one step, or not at all. A program has to open a transaction before it can change anything. Everything inside that transaction commits together, under one name, as a single entry in your undo history that Cmd-Z takes back in one press. If it fails partway, the whole thing rolls back rather than leaving you half a construction.

Reading needs none of this. A program can look at the document at any time without taking the lock.

What it can do

Today it can:

• Read the model: a summary, a named object, a search, and a consistency check.
• Place geometry: points, segments, lines, circles, polygons, rectangles, squares, perpendicular bisectors, and intersection points.
• Change what is there: move a point, rename, group, delete.
• Read the node graph: a summary, one node, the wires, a trace, and an evaluation.
• Set a node parameter.
• Open and close the node editor, and report which windows are open.

Known limits

All of these are true today and are expected to change.

• Nothing in the app tells you a program is working. There is no banner and no cancel button, so the ways to stop it are the ones above.
• The program cannot be told it was canceled. It finds out when its next instruction fails.
• Styling is not carried, so a script cannot set how something looks.
• Saving is not usable yet, even though the protocol describes it.

Caution

Run with the Nodes pane closed. With both the modeling window and the node editor open, changes made from outside the normal editing path can be lost: the two windows reconcile with each other and the newer objects go. This is being fixed. Until it is, close the node editor before starting a session.

Related

• Preferences: where the control lives, under General.
• CLI commands: every command a program can send.
• Keeping the node graph tidy: the node editor window, which the caution above is about.
• Undo for the node graph: the undo history a committed transaction becomes one entry in.

< Previous: Language & i18n | Next: CLI commands >