locus cli

Home > locus-cli

< Previous: CLI server | Next: CLI commands >

CLI

locus-cli

A command line into a running Locus Studio. You get a locus> prompt and type commands at the document you have open.

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.

Warning

macOS and Linux only for now. The Windows side exists in the code but is not offered yet, and there is nothing to install. Two things are open against it, so do not treat the Windows path as available.

What you need first

• Locus Studio running, with a document open.
• The CLI server started, from Settings, under General. See CLI server.
• locus-cli itself, which is a separate download per platform rather than something inside the app, because the app and the command line are signed separately.

The shell finds the running app by itself. The app writes a small file when it starts and removes it when it exits, and the shell reads that; there is no address to configure and nothing to pass on the command line.

A first run

Start it, and it prints what it connected to and which document is open. Then it waits:

locus> model point --at 0,0 --name "origin"
  ok
  committed, one undo step

Type help for the shell's own commands, describe for the list of what the app accepts, and quit to leave.

What one undo takes back

This is worth knowing before you type anything that changes the drawing.

• One typed line is one undo step.
• A whole pasted block is one undo step, not one per line.
• If any line in a paste fails, nothing in the paste is kept. The whole block rolls back.
• A command that only reads makes no undo step at all.
• Comments and blank lines are skipped, so a file full of them is safe.

Pasting a saved file

A saved .locuscli file pastes in as it stands. The two forms both work at the prompt, so you do not have to convert anything:

model point \
  --at 0,0 \
  --name "origin"

is what a file is written in, and the lower-level form the protocol uses works too. The shell carries no list of commands of its own: it asks the app at startup and hands anything it does not recognize to the app to read. That is why a new command never needs a new download of the shell.

Caution

Five commands will roll your whole paste back. new, pencil, save, fill and paint are window features with no command behind them. Pasted, the app refuses the line, and because the paste is one transaction the refusal takes the entire block with it. You see the failure and then rolled back, nothing was kept.

So a file pastes in cleanly as long as it holds none of those five. If it does, either delete those lines first or run the file through the runner instead, which skips them and carries on. This is why the eightfold example file produces nothing when pasted: its first two lines are new and pencil.

The runner can also translate a file for the prompt, and the output pipes in. The difference is worth knowing: piping makes every line its own undo step, where pasting makes the whole block one.

Staying in control

While a client is working, the window takes a lock, and the lock gives way to you.

• You are never locked out of looking. Pan, zoom, select, inspect and read anything you like. Only changes are intercepted.
• Your first edit cancels the client, and the work is rolled back before your edit lands, so your change is never built on top of something about to disappear.
• It also gives up on its own after a time limit, and if the client disconnects or dies.
• A rollback never restores over your own work. If the document moved by a path the lock did not catch, the run cancels without restoring, so the client's objects survive and you can undo them yourself.

Nothing in the app announces that a client is working. There is no banner, no cancel button, and the Escape key does not stop a run.

Two things to watch

Close the Nodes pane for a command line session. With the node editor in its own window, changes made from outside the normal editing path can be lost: both windows answer the same broadcast and the other one can replace the document wholesale, so writes land and then vanish. Asking the app about its windows returns a note saying so, specifically so a client finds out before it writes rather than forty commands later.

Give things names of two letters or more. Placed points are named automatically A, B and so on, then A1, B1, from a counter that does not check what is already taken. Name a point O by hand and it collides with the fifteenth automatic name; C1 collides with the twenty-ninth. From then on every reference to that name is refused as ambiguous, including references in a script that worked yesterday, and the failure shows up a long way from its cause. This is a bug, already filed, not behavior to work around.

Related

• CLI server: turning it on, and what the Settings row shows.
• CLI commands: the commands you can write, and what each one takes.
• Preferences: where the control lives, under General.

< Previous: CLI server | Next: CLI commands >