Unluminous

unluminous-cli 1.3.3

Command reference

Every one of the 296 commands, written from the catalogue unluminous-cli itself reads. Type unluminous-cli <area> <verb> --help for the same text in a terminal. The command line chapter explains how the commands work.

Flags every command takes

--instance <pid|port|path>
Which Unluminous to talk to when several are running: its process id, its port, or part of its project's path. Needs no saying in a terminal or an agent a window started, which set UNLUMINOUS_INSTANCE to their own window.
--json
Print the whole reply as JSON. This is what a program or an agent should always pass.
--quiet
Print nothing when it worked. The exit code still says whether it did.
--timeout <milliseconds>
How long to wait for an answer. 15000 by default. Lower it to fail fast; a command that waits for something of its own, such as `terminal read --wait-for`, is still waited out in full.
--dry-run
Print the command and the arguments that would be sent, and send nothing. Needs no running Unluminous.
--no-color
Never color the output. NO_COLOR in the environment does the same.
--help
Print help for the command, or for the whole CLI, and do nothing else.
--version
Print the version and do nothing else.

The window

Everything about the window in one answer, starting and closing windows, and the catalogue itself.

status

unluminous-cli status [--section <name>]

Everything about the window in one answer: its version and build date, the project, the tabs, the panes, the terminal, who holds the keyboard, the modal that is open, the settings and git. Ask for one part with --section and the answer is only that part. --section keyboard is the one to read when typing goes somewhere unexpected: it says which surface Unluminous gave the keys to, and whether a text box anywhere has egui's own focus - while one has, every other surface stands aside. --section servers says what each language server is doing.

--section <name>
One part of the answer: editor, tabs, panes, panels, explorer, terminal, keyboard, modal, settings, git, servers, window, project or message. Several, comma-separated, for more than one. The whole answer when it is left out.
unluminous-cli status --json
unluminous-cli status --section servers --json

instances

unluminous-cli instances

The Unluminous windows that are running, with the port and the project of each. Answered without talking to any of them.

unluminous-cli instances --json

launch

unluminous-cli launch [folder] [--timeout <milliseconds>] [--no-wait]

Start another Unluminous on a folder and wait until it answers.

[folder]
The project to open. The current folder when it is left out.
--timeout <milliseconds>
How long to wait for the new window to answer. 20000 by default.
--no-wait
Return as soon as the process starts, without waiting for it to answer.
unluminous-cli launch C:\jason\dev\unluminous
unluminous-cli launch . --timeout 40000

setup

unluminous-cli setup [--check] [--remove] [--force] [--agents <list>] [--path] [--no-path] [--no-voice] [--installer]

Finish setting Unluminous up on this machine: put unluminous-cli on the path, connect every coding agent found (Claude Code, Codex, OpenCode, Pi) to Unluminous's MCP server, say which API keys are set, check that the server answers, download the speech model for dictation when this build did not come with it, and ask about the microphone. The installers run it; running it again changes nothing. An entry an agent already has that points at another Unluminous is left alone. Restart an agent to see the tools it was given.

--check
Say what is and is not set up, and change nothing.
--remove
Take out every unluminous entry that starts this program, and the path entry setup made. Entries pointing at another program are left.
--force
Replace an agent's unluminous entry, or a link, that points at another program.
--agents <list>
Only these agents, separated by commas: claude, codex, opencode, pi. All of them by default.
--path
Put unluminous-cli on the path even when this is a build rather than an installed copy.
--no-path
Leave the path alone.
--no-voice
Do not download the speech model or ask about the microphone. The Windows installer passes it, because its own voice task does that.
--installer
Also write the report to setup.log in Unluminous's settings folder. The Windows installer passes it, because nothing reads the output of a program it runs hidden.
unluminous-cli setup
unluminous-cli setup --check --json
unluminous-cli setup --agents claude
unluminous-cli setup --remove

quit

unluminous-cli quit

Close the window. Its settings and what it had open are written down first, as they are when it is closed by hand.

unluminous-cli quit

commands

unluminous-cli commands [name]

Every command this CLI has, as data: the areas, the arguments, the flags and the examples. This is what to read first when a program or an agent is driving Unluminous.

[name]
One command, such as terminal send, instead of all of them.
unluminous-cli commands --json
unluminous-cli commands "modal open" --json

version

unluminous-cli version

What version this command line tool is. The version and build date of the Unluminous editor it is talking to are in status, and modal open about shows them in the window.

unluminous-cli version

tab

Open, show, close, save, reload and move the tabs in the editing area.

tab open

unluminous-cli tab open <path> [--permanent]

Open a file in a tab and show it. A picture opens as a picture; anything else opens as text.

<path>
The file. A relative path is resolved against the project folder.
--permanent
Open it as a tab of its own rather than reusing the tab a single click reuses.
unluminous-cli tab open README.md
unluminous-cli tab open design/style-guide.md --permanent

tab list

unluminous-cli tab list

The tabs that are open, in order, with the path, the name and whether each has unsaved changes.

unluminous-cli tab list --json

tab show

unluminous-cli tab show <tab>

Show a tab that is already open.

<tab>
Its number counting from 0, or its name, or its path.
unluminous-cli tab show 2
unluminous-cli tab show README.md

tab close

unluminous-cli tab close [tab] [--discard]

Close a tab. A tab with unsaved changes is written first, which is what closing one by hand does. Closing the last one leaves an empty untitled tab rather than no tab at all.

[tab]
Its number, name or path. The tab that is showing when it is left out.
--discard
Close it without writing what was typed into it.
unluminous-cli tab close
unluminous-cli tab close notes.md
unluminous-cli tab close --discard

tab reopen

unluminous-cli tab reopen

Open the last tab that was closed again, in the pane it was closed from. The ten most recent are remembered while this window is open, so running it again reaches the one before that. The file is read from the disk.

unluminous-cli tab reopen

tab next

unluminous-cli tab next

Show the next tab, wrapping round at the end.

unluminous-cli tab next

tab previous

unluminous-cli tab previous

Show the previous tab.

unluminous-cli tab previous

tab move

unluminous-cli tab move <position> [--tab <tab>] [--pane <number>]

Move a tab along its strip, or into another pane, which is what dragging it does. The position counts the tabs of the pane it is going to, as they are on the screen now.

<position>
Where it goes, counting from 0. Past the end means the end.
--tab <tab>
Which tab to move: its number, name or path. The tab that is showing when it is left out.
--pane <number>
Which pane to move it into, counting from 0. The pane it is already in when it is left out.
unluminous-cli tab move 0
unluminous-cli tab move 0 --tab notes.md --pane 1

tab save

unluminous-cli tab save

Write the tab that is showing back to its file.

unluminous-cli tab save

tab save-as

unluminous-cli tab save-as <path>

Write the tab that is showing to another file, and go on editing that one.

<path>
Where to write it.
unluminous-cli tab save-as notes/copy.md

tab reload

unluminous-cli tab reload [--discard]

Read the file from disk again. A tab with unsaved changes is refused unless you say to throw them away, because there is no undo for that.

--discard
Reload even though the tab has unsaved changes, losing them.
unluminous-cli tab reload
unluminous-cli tab reload --discard

editor

Read and change the text of the tab that is showing: the caret, the selection, find and replace, definitions, references, rename and completion.

editor status

unluminous-cli editor status

What the tab that is showing holds: its path, how many lines, where the caret is, what is selected, whether it has unsaved changes and which view mode it is in.

unluminous-cli editor status --json

editor text

unluminous-cli editor text [--from-line <number>] [--to-line <number>]

Read the text of the tab that is showing.

--from-line <number>
The first line to read, counting from 1.
--to-line <number>
The last line to read, counting from 1.
unluminous-cli editor text
unluminous-cli editor text --from-line 1 --to-line 20

editor set-text

unluminous-cli editor set-text [text] [--from-file <path>]

Replace everything in the tab that is showing. One undo puts it back.

[text]
The new text. Use --from-file instead for anything long.
--from-file <path>
Read the new text from this file rather than from the command line.
unluminous-cli editor set-text # Notes
unluminous-cli editor set-text --from-file draft.md

editor insert

unluminous-cli editor insert <text>

Type text at the caret, replacing the selection if there is one. It types exactly what it is given: there is no auto-indent, so a line of a function body has to carry its own leading spaces.

<text>
What to type, exactly as it will appear. \n is a new line and \t is a tab. Nothing is indented for you.
unluminous-cli editor insert Hello
unluminous-cli editor insert "one\ntwo"

editor caret

unluminous-cli editor caret [--line <number>] [--column <number>] [--top]

Read where the caret is, or move it. Lines and columns count from 1, which is what the status bar shows.

--line <number>
The line to move to.
--column <number>
The column to move to. The start of the line when it is left out.
--top
Scroll so the caret's line is at the top of the view, as a link to a function does.
unluminous-cli editor caret
unluminous-cli editor caret --line 42 --column 5
unluminous-cli editor caret --line 120 --top

editor select

unluminous-cli editor select [--all] [--none] [--from-line <number>] [--from-column <number>] [--to-line <number>] [--to-column <number>]

Select some of the text, all of it, or none of it.

--all
Select the whole document.
--none
Drop the selection, leaving the caret where it was.
--from-line <number>
The line the selection starts on.
--from-column <number>
The column it starts at. 1 when it is left out.
--to-line <number>
The line it ends on.
--to-column <number>
The column it ends at. The end of the line when it is left out.
unluminous-cli editor select --all
unluminous-cli editor select --from-line 3 --to-line 6

editor indent

unluminous-cli editor indent [--space]

Indent each line the selection touches, or the line the caret is on when nothing is selected, by one tab at the start of the line — or one space with --space. This is what Tab and Space do over a selection in the editing area, and the selection stays over the text it covered.

--space
Indent with a space rather than a tab, which is what the Space key does.
unluminous-cli editor indent
unluminous-cli editor indent --space

editor dedent

unluminous-cli editor dedent [--space]

Remove one indent from each line the selection touches, or the caret's line when nothing is selected — one tab, or one space with --space. This is what Shift+Tab and Shift+Space do over a selection. A line with none, or indented with the other unit, is left alone.

--space
Remove a space rather than a tab, which is what Shift+Space does.
unluminous-cli editor dedent
unluminous-cli editor dedent --space

editor comment

unluminous-cli editor comment [--toggle] [--block]

Comment or uncomment the lines the selection touches, or the caret's line when nothing is selected, with the marker this file's language uses. It is the same command both ways. The marker comes from the plugin that claims the file, so a language that names none is refused rather than guessed at.

--toggle
Use the line comment marker, such as // or #. This is what it does when neither flag is given.
--block
Use the block comment markers instead, such as /* and */, wrapping the whole selection once rather than each line.
unluminous-cli editor comment --toggle
unluminous-cli editor comment --block

editor lines

unluminous-cli editor lines <duplicate|move|join|sort> [--by <number>]

Edit whole lines: duplicate, move up or down, join, or sort. Each is one undo step, and each is about the lines the selection touches, or the caret's line when nothing is selected. Sort needs a selection.

<what>
duplicate, move, join or sort.
--by <number>
For move: how far and which way. -1 is up and 1 is down, which is what Alt+Up and Alt+Down send.
unluminous-cli editor lines duplicate
unluminous-cli editor lines move --by -1
unluminous-cli editor lines join
unluminous-cli editor lines sort

editor bracket

unluminous-cli editor bracket [--offset <bytes>] [--line <number>] [--column <number>] [--go]

The bracket answering the one beside the caret, as both byte offsets and both line and column positions. It tells a bracket in a comment or a string from one in the code, which a search for the character cannot. --go moves the caret to it.

--offset <bytes>
Ask about this position in the file rather than about the caret.
--line <number>
Ask about this line, counting from 1.
--column <number>
The column on that line. 1 when it is left out.
--go
Move the caret to the bracket that answers it.
unluminous-cli editor bracket --json
unluminous-cli editor bracket --go

editor trim

unluminous-cli editor trim

Take the trailing whitespace off every line of the tab that is showing, as one undo step. The editor.trim setting does this on every save; this asks for it once. Refused for a Markdown file, where two trailing spaces are a line break.

unluminous-cli editor trim

editor undo

unluminous-cli editor undo

Undo the last edit in the tab that is showing.

unluminous-cli editor undo

editor redo

unluminous-cli editor redo

Redo the edit that was last undone.

unluminous-cli editor redo

editor view

unluminous-cli editor view <raw|side|preview>

Choose how a file with a preview is shown: the source, the source and the preview side by side, or the preview. Markdown and Mermaid files have one; nothing else does, and only a file with a preview can be shown any way but raw.

<mode>
raw, side or preview.
unluminous-cli editor view preview
unluminous-cli editor view side

editor scroll

unluminous-cli editor scroll [--line <number>] [--to <points>] [--top] [--bottom] [--preview]

Read how far the tab that is showing is scrolled, or scroll it. With no flags it reports both halves of the side by side view. In side by side the other half follows, exactly as it does when you scroll with the wheel.

--line <number>
Scroll so this line is at the top, counting from 1.
--to <points>
Scroll to this many points down the page.
--top
Scroll to the top.
--bottom
Scroll to the bottom.
--preview
Scroll the Markdown preview rather than the source.
unluminous-cli editor scroll --json
unluminous-cli editor scroll --line 120
unluminous-cli editor scroll --preview --top

editor preview

unluminous-cli editor preview

Read the preview of the tab that is showing: a Markdown page as plain text with where its pictures, diagrams and links are, or, for a Mermaid file, what the diagram came out as. Under --json each link reports the bytes of its words and the address it goes to, with a reference definition already resolved, so a document's links can be read without parsing its source.

unluminous-cli editor preview --json

editor preview-select

unluminous-cli editor preview-select [--from <bytes>] [--to <bytes>] [--all] [--none] [--copy]

What is selected in the Markdown preview, and selecting something in it. The preview is read only, so a selection there is for reading and copying rather than editing; the offsets are into the preview's own text, which is what editor preview prints.

--from <bytes>
Where the selection starts in the preview's text.
--to <bytes>
Where it ends. The end of the text when it is left out.
--all
Select the whole preview.
--none
Select nothing.
--copy
Put whatever is selected on the clipboard.
unluminous-cli editor preview-select --json
unluminous-cli editor preview-select --all --copy
unluminous-cli editor preview-select --from 0 --to 40

editor definition

unluminous-cli editor definition [name] [--offset <bytes>] [--line <number>] [--column <number>] [--open]

Where a name is defined, from Unluminous's live open tabs and project symbol index. Give the name directly or leave it out for the word at the caret; every candidate is printed best first and --open navigates through the editor.

[name]
The name to find. The word at the caret when it is left out.
--offset <bytes>
Ask about this position in the file rather than about the caret.
--line <number>
Ask about this line, counting from 1.
--column <number>
The column on that line. 1 when it is left out.
--open
Go to the best candidate, opening its file as a tab.
unluminous-cli editor definition --json
unluminous-cli editor definition Rect --open --json
unluminous-cli editor definition --line 42 --column 9 --open

editor find

unluminous-cli editor find [text] [--match-case] [--whole-word] [--next] [--previous] [--close] [--limit <number>]

Find text in the file that is showing, the way Ctrl+F does: the count, every match's line and column, and the one that is current selected in the window so a screenshot shows it. Use this rather than reading the whole file to locate a string. --replace turns it into an edit; without it nothing is changed.

[text]
What to look for. The bar's current search when it is left out.
--match-case
Only matches spelt with the same capitals count.
--whole-word
Only matches with no letter, digit or underscore either side of them count.
--next
Move to the match after the one that is current, wrapping round the end of the file.
--previous
Move to the match before it, wrapping round the start.
--close
Put the Find bar away, leaving the caret on the match it was on.
--limit <number>
List at most this many matches. 50 when it is left out, and 0 means all of them.
unluminous-cli editor find relayout --json
unluminous-cli editor find Rect --whole-word --match-case --json
unluminous-cli editor find --next --json
unluminous-cli editor find --close

editor replace

unluminous-cli editor replace <text> <with> [--match-case] [--whole-word] [--all] [--apply]

Replace text in the file that is showing. Use this for a string, a comment, a URL or a number - editor rename is for a symbol and is the better tool when it applies, because it knows code from comments. Without --apply it says how many matches there are and changes nothing. Applying is one undo step whether it changes one match or four hundred.

<text>
What to look for.
<with>
What to put in its place. Give an empty string to delete it.
--match-case
Only matches spelt with the same capitals count.
--whole-word
Only matches with no letter, digit or underscore either side of them count.
--all
Replace every match rather than only the one that is current.
--apply
Make the change. Without it the count is printed and nothing is edited.
unluminous-cli editor replace teh the --all --json
unluminous-cli editor replace teh the --all --apply
unluminous-cli editor replace 0.34.2 0.35.0 --match-case --all --apply

editor references

unluminous-cli editor references [name] [--timeout <milliseconds>] [--code-only]

Use this instead of grep to find every place a name is used across the project: the file, line, column and whether it is code or a word inside a comment or string. Reads unsaved open tabs as they stand and everything else from the disk.

[name]
The name to look for. The word at the caret when it is left out.
--timeout <milliseconds>
How long to wait for the search. 10000 by default.
--code-only
Leave out the matches inside comments and strings.
unluminous-cli editor references --json
unluminous-cli editor references open_the_match --json

editor rename

unluminous-cli editor rename <new-name> [--name <text>] [--scope <file|project>] [--include <comments,strings>] [--timeout <milliseconds>] [--apply]

Use this instead of file edits to rename a symbol everywhere through Unluminous's role-aware references. Comments and strings stay untouched unless included; without --apply it previews. Applying edits each open tab as one undo step, leaving it with unsaved changes, and writes every file that is not open straight to the disk — the answer counts the two apart, as wrote and openTabs.

<new-name>
What to call it. It has to be a word of this language and not one of its keywords.
--name <text>
Rename this name rather than the word at the caret.
--scope <file|project>
Which files to change. The default follows what the name resolves to: a variable or a name with no known definition is this file, and a function, type, constant or module is the project.
--include <comments,strings>
Also change the matches inside comments or strings, which are left alone by default.
--timeout <milliseconds>
How long to wait for the search that finds them. 10000 by default.
--apply
Make the change. Without it the change set is printed and nothing is edited or written.
unluminous-cli editor rename open_the_result --json
unluminous-cli editor rename open_the_result --apply
unluminous-cli editor rename total --scope project --include comments --apply

editor complete

unluminous-cli editor complete [--offset <bytes>] [--line <number>] [--column <number>] [--stem <text>] [--limit <number>] [--choose <name>] [--after <text>] [--wait <milliseconds>] [--explain]

The names a word could become, best first, with what each row is and where it came from. By default the word is read from the document at the caret; --stem asks hypothetically without editing the document. Inside an import the rows are what can be imported instead. --choose applies a real document row exactly as Enter would, and takes the row's name rather than its position.

--offset <bytes>
Ask about this position in the file rather than about the caret.
--line <number>
Ask about this line, counting from 1.
--column <number>
The column on that line. 1 when it is left out.
--stem <text>
Ask what this hypothetical word would offer at the position, without inserting it or changing the document.
--limit <number>
Print at most this many rows. 50 when it is left out, and 0 means all of them.
--choose <name>
Apply this row to the word being typed, as Enter would. It is the completion's **name**, never a row number: --choose 0 is refused with the names there are.
--after <text>
Ask as if this text were typed first: --after . lists the members of the value before the caret.
--wait <milliseconds>
How long to wait for the language server's rows. 300 by default; 0 answers from the project's structure alone.
--explain
Say why each row is where it is: every fact the ranking read about it (how the word matched, which sources offered it, its kind against the place, how near its last use is, the server's own order) and the score the ranking gave it. The rows written nearest the caret are added after the first --limit, up to --limit more, each with its rank.
unluminous-cli editor complete --json
unluminous-cli editor complete --explain --limit 3 --json
unluminous-cli editor complete --stem ar --limit 5 --json
unluminous-cli editor complete --after . --limit 10 --json
unluminous-cli editor complete --limit 5 --json
unluminous-cli editor complete --choose draw_frame
unluminous-cli editor complete --choose ./layout

editor signature

unluminous-cli editor signature [--wait <milliseconds>]

The function whose brackets the caret is inside, with its parameters and which one is being typed. From the language server when one runs, otherwise from the project's definitions.

--wait <milliseconds>
How long to wait for the language server. 300 by default.
unluminous-cli editor signature --json

editor navigate-back

unluminous-cli editor navigate-back

Go back to where the caret was before the last jump, reopening the file if its tab was closed.

unluminous-cli editor navigate-back

editor navigate-forward

unluminous-cli editor navigate-forward

Undo a navigate-back. Cleared by any new jump, exactly as a browser's forward button is.

unluminous-cli editor navigate-forward

pane

Split the editing area into panes, and move tabs between them.

pane list

unluminous-cli pane list

The panes the editing area is split into, with the tabs in each, which tab is showing in each, and which pane has the keyboard.

unluminous-cli pane list --json

pane split

unluminous-cli pane split

Put a pane to the right of the one with the keyboard and move the tab that is showing into it. A pane holding only that tab keeps it and the new pane opens empty.

unluminous-cli pane split

pane move

unluminous-cli pane move <left|right>

Move the tab that is showing into the pane beside it.

<direction>
left or right.
unluminous-cli pane move right
unluminous-cli pane move left

pane place

unluminous-cli pane place <pane> <position>

Move a whole pane and its tabs along the row, as dragging its strip's empty part does.

<pane>
Which pane, from 0.
<position>
Panes before it once moved, counted as now: 0 is far left.
unluminous-cli pane place 0 2

pane focus

unluminous-cli pane focus <pane>

Put the keyboard in a pane, so that the next file opened lands in it.

<pane>
Its number counting from 0, left to right.
unluminous-cli pane focus 1

pane width

unluminous-cli pane width <pane> <fraction>

Set one pane's share of the editing area, which is what dragging the divider between two panes does. The other panes share what is left.

<pane>
Its number counting from 0.
<fraction>
Its share of the width, between 0.05 and 0.95.
unluminous-cli pane width 0 0.35

pane unsplit

unluminous-cli pane unsplit

Fold the pane that has the keyboard into the one beside it, keeping its tabs.

unluminous-cli pane unsplit

pane unsplit-all

unluminous-cli pane unsplit-all

Put every tab back into one pane.

unluminous-cli pane unsplit-all

explorer

The file explorer: show it, filter it, expand folders, make, copy, move and delete files.

explorer show

unluminous-cli explorer show

Show the file explorer down the left.

unluminous-cli explorer show

explorer hide

unluminous-cli explorer hide

Collapse the file explorer, leaving the rail of buttons.

unluminous-cli explorer hide

explorer toggle

unluminous-cli explorer toggle

Show the explorer if it is hidden, and hide it if it is showing.

unluminous-cli explorer toggle

explorer width

unluminous-cli explorer width [points]

Read how wide the explorer is, or set it. The same measurement dragging its edge changes.

[points]
How wide to make it, from 150 to 620. Read it when this is left out.
unluminous-cli explorer width 320

explorer filter

unluminous-cli explorer filter [text]

Read the explorer's filter box, or type into it. The tree then shows only what matches.

[text]
What to filter by. The box is cleared when this is left out.
unluminous-cli explorer filter tdd
unluminous-cli explorer filter

explorer expand

unluminous-cli explorer expand <path>

Open a folder in the tree, and every folder above it.

<path>
The folder, relative to the project or absolute.
unluminous-cli explorer expand crates/unluminous-app/src

explorer collapse

unluminous-cli explorer collapse [path]

Shut a folder in the tree.

[path]
The folder. Every open folder is shut when this is left out.
unluminous-cli explorer collapse crates
unluminous-cli explorer collapse

explorer tree

unluminous-cli explorer tree [--limit <number>]

The rows the explorer is showing, in order, with the depth of each and whether it is a folder.

--limit <number>
At most this many rows. 200 by default.
unluminous-cli explorer tree --json

explorer files

unluminous-cli explorer files [--limit <number>]

Every file in the project that Unluminous searches, which leaves out what a build wrote: target, node_modules and __pycache__.

--limit <number>
At most this many paths. 500 by default.
unluminous-cli explorer files --limit 20 --json

explorer select-open-file

unluminous-cli explorer select-open-file

Scroll the explorer to the file that is showing and select it, opening out the folders above it. It happens on its own when the tab changes; this asks for it by hand.

unluminous-cli explorer select-open-file

explorer select

unluminous-cli explorer select [path]

Set the row the explorer's own cursor is on, which is what Delete is about, or read it when no path is given. It is not the same as the tab that is showing.

[path]
The file or folder to select.
unluminous-cli explorer select README.md
unluminous-cli explorer select --json

explorer choose

unluminous-cli explorer choose <path> [--add] [--range]

Choose rows in the explorer for a cut, a copy, a move or a delete, the way a click does: on its own, added to or taken from what is chosen as Ctrl or Cmd with the click does, or every row from the last one chosen to this one as Shift with the click does. Cut, Copy and Paste on the explorer's menu then act on every chosen row.

<path>
The file or folder to choose.
--add
Add it to the rows already chosen, or take it out when it is one of them.
--range
Choose every row from the last one chosen to this one.
unluminous-cli explorer choose src/one.rs
unluminous-cli explorer choose src/two.rs --add
unluminous-cli explorer choose src/nine.rs --range --json

explorer copy-in

unluminous-cli explorer copy-in <path> <folder>

Copy a file or a folder from anywhere into a folder of the project, the same thing dropping it on the explorer from Finder or Explorer does. A name already taken in the folder gets a number rather than being overwritten.

<path>
The file or folder to copy in, from anywhere on the machine. A relative path is read from the project.
<folder>
The project folder it goes into.
unluminous-cli explorer copy-in C:/Users/me/Downloads/logo.png assets

explorer delete

unluminous-cli explorer delete <path>

Delete a file or a folder. On Windows it goes to the Recycle Bin; everywhere else it is gone. No question is asked, because typing the command is the deliberate act the question exists to ask for.

<path>
The file or folder to delete.
unluminous-cli explorer delete notes/old.md

explorer move

unluminous-cli explorer move <path> <folder> [--dry-run] [--no-refactor]

Move a file or a folder into another folder, rewriting every import, use line and mod declaration in the project that names it. The same thing dragging a row in the explorer does.

<path>
The file or folder to move.
<folder>
The folder it goes into.
--dry-run
Print the whole change set and change nothing at all.
--no-refactor
Move the bytes and leave every reference to them alone.
unluminous-cli explorer move src/app/layout.ts src/draw
unluminous-cli explorer move src/app/layout.ts src/draw --dry-run --json

explorer new-file

unluminous-cli explorer new-file <path>

Make an empty file, create its parent folders, update Unluminous's live tree and open it in a tab. The same thing New -> File on the explorer's right click menu does, without the dialog.

<path>
Where the file goes, relative to the project or absolute.
unluminous-cli explorer new-file notes/today.md

explorer new-folder

unluminous-cli explorer new-folder <path>

Make a folder and every folder above it, updating Unluminous's live tree immediately. The same thing New -> Folder on the explorer's right click menu does, without the dialog.

<path>
Where the folder goes, relative to the project or absolute.
unluminous-cli explorer new-folder src/services

explorer new-project

unluminous-cli explorer new-project <name> [--location <folder>] [--no-git]

Make a project folder, start a git repository in it, and open it in a window of its own — which is what File -> Create Project... does without the dialog. The folder is <location>/<name>; an existing folder with anything in it is refused rather than opened, and a name with a path separator in it is refused because a project name is a folder name.

<name>
What the project folder is called.
--location <folder>
The folder the project goes in. Beside the project that is open when it is not given, which is where the dialog starts too.
--no-git
Do not run git init in it. A git repository is made otherwise.
unluminous-cli explorer new-project my-thing
unluminous-cli explorer new-project my-thing --location C:/jason/dev
unluminous-cli explorer new-project scratch --no-git

explorer reload

unluminous-cli explorer reload

Read the project's folders again, so anything another program has just made appears. It happens on its own within a second; this asks for it now.

unluminous-cli explorer reload

explorer reveal

unluminous-cli explorer reveal <path>

Show a path in the platform's own file manager: Explorer on Windows, Finder on macOS.

<path>
The file or folder.
unluminous-cli explorer reveal README.md

terminal

The terminal tile: its tabs, sending a command to a shell, and reading what is on its screen.

terminal show

unluminous-cli terminal show

Show the terminal along the bottom, opening a shell in the project folder if there is not one already.

unluminous-cli terminal show

terminal hide

unluminous-cli terminal hide

Put the terminal away. The shells keep running.

unluminous-cli terminal hide

terminal toggle

unluminous-cli terminal toggle

Show the terminal if it is hidden, and hide it if it is showing.

unluminous-cli terminal toggle

terminal new

unluminous-cli terminal new

Start another shell in a tab of its own, and show it.

unluminous-cli terminal new

terminal list

unluminous-cli terminal list

The terminal tabs: the name of each, which one is showing, and the folder each one's shell is in, which is where it would reopen.

unluminous-cli terminal list --json

terminal select

unluminous-cli terminal select [index] [--tab <index>]

Show one of the terminal tabs. The only verb that changes which tab is showing.

[index]
Its number, counting from 0. The --tab flag when it is given.
--tab <index>
Which tab to show, counting from 0.
unluminous-cli terminal select 1
unluminous-cli terminal select --tab 1

terminal close

unluminous-cli terminal close [index] [--tab <index>]

Close a terminal tab. Closing the last one puts the terminal away.

[index]
Its number. The --tab flag when it is given, the tab that is showing when both are left out.
--tab <index>
Which tab to close, counting from 0. The one that is showing when it is left out.
unluminous-cli terminal close
unluminous-cli terminal close --tab 1

terminal rename

unluminous-cli terminal rename <name> [--tab <index>]

Call a terminal tab something else. The name stays put when the program in the tab sets a title of its own; an empty name puts the tab back to being named after its program.

<name>
What to call it. Everything after the verb is taken as the name, so it needs no quotes.
--tab <index>
Which tab, counting from 0. The one that is showing when it is left out.
unluminous-cli terminal rename build
unluminous-cli terminal rename --tab 1 the long running one

terminal move

unluminous-cli terminal move <position> [--tab <index>]

Move a terminal tab along the strip, which is what dragging one does.

<position>
Where it goes, counting the tabs as they are on the screen now from 0.
--tab <index>
Which tab to move, counting from 0. The one that is showing when it is left out.
unluminous-cli terminal move 0
unluminous-cli terminal move --tab 2 0

terminal send

unluminous-cli terminal send [text] [--tab <index>] [--no-enter] [--key <name>]

Send a command to the shell in a terminal tab, the one that is showing when --tab is left out. Naming a tab does not show it. Enter is pressed for you unless you say not to.

[text]
The command. Everything after the verb is taken as the command, so it needs no quotes.
--tab <index>
Which tab to send to, counting from 0. The one that is showing when it is left out.
--no-enter
Type the text and leave it on the prompt without running it.
--key <name>
Send a key instead of text: enter, tab, escape, up, down, left, right, backspace, ctrl-c, ctrl-d, ctrl-l.
unluminous-cli terminal send git status
unluminous-cli terminal send --tab 1 cargo check
unluminous-cli terminal send --key ctrl-c
unluminous-cli terminal send --no-enter cd ..

terminal read

unluminous-cli terminal read [--tab <index>] [--lines <number>] [--wait-for <text>] [--timeout <milliseconds>]

Read what a terminal tab has on its screen, the one that is showing when --tab is left out. Reading a tab does not show it.

--tab <index>
Which tab to read, counting from 0. The one that is showing when it is left out.
--lines <number>
Only the last so many lines.
--wait-for <text>
Wait until this text is on the named tab's screen before answering, which is how to wait for a command to finish.
--timeout <milliseconds>
How long to wait for --wait-for. 10000 by default.
unluminous-cli terminal read --lines 20
unluminous-cli terminal read --tab 1
unluminous-cli terminal read --tab 1 --wait-for "$" --timeout 15000

terminal height

unluminous-cli terminal height [points]

Read how tall the terminal tile is, or set it. The same measurement dragging its top edge changes.

[points]
How tall to make it. Read it when this is left out.
unluminous-cli terminal height 400

run

Run configurations: keep one, start and stop it, and read what it wrote.

run list

unluminous-cli run list

The project's run configurations: the name, the command, the folder and the environment of each, whether it is permanent, temporary or a suggestion, and what its run is doing.

unluminous-cli run list --json

run add

unluminous-cli run add <name> <command> [--directory <path>] [--env <pairs>]

Keep a new run configuration in the project. The command is one line: the first word is the program and the rest are its arguments, and no shell runs it, so nothing is expanded and && is an argument. It says so when the program cannot be found on this window's PATH, and keeps the configuration anyway.

<name>
What to call it, which is what the widget and the Run menu show.
<command>
The command line. Everything after the name is taken as the command, so it needs no quotes.
--directory <path>
The folder it runs in, relative to the project. The project itself when it is left out.
--env <pairs>
NAME=value pairs separated by semicolons.
unluminous-cli run add "Dev server" node server.js --port 3000
unluminous-cli run add build cargo build --release --directory crates/unluminous-app
unluminous-cli run add serve npm run dev --env "PORT=3000; DEBUG=app:*"

run set

unluminous-cli run set <name> [--command <text>] [--directory <path>] [--env <pairs>] [--set-env <NAME=value>] [--unset-env <NAME>]

Change a run configuration's command, folder or environment variables.

<name>
The configuration, as run list gives it.
--command <text>
The new command line.
--directory <path>
The folder it runs in. Empty means the project itself.
--env <pairs>
NAME=value pairs split by semicolons, replacing all of them.
--set-env <NAME=value>
Add or change one variable.
--unset-env <NAME>
Remove one variable.
unluminous-cli run set "Dev server" --set-env PORT=4000

run remove

unluminous-cli run remove <name>

Take a run configuration away. One whose program is still running is stopped first.

<name>
The configuration, as run list gives it.
unluminous-cli run remove "Dev server"

run start

unluminous-cli run start [name]

Run a configuration, showing the run tile. Starting one that is already running stops it and starts it again rather than making a second copy. A detector's suggestion started this way is kept as a temporary configuration. A program that could not be started is a failure carrying the reason, not a reply that says nothing ran.

[name]
The configuration. The chosen one when it is left out.
unluminous-cli run start
unluminous-cli run start "Dev server"

run stop

unluminous-cli run stop [name]

Stop a run: the interrupt a program can catch, and a hard kill two seconds later or on a second stop. The tab stays, holding what the program wrote. Stopping when nothing is running is a failure that says so rather than a quiet success.

[name]
The configuration. The chosen one when it is left out.
unluminous-cli run stop
unluminous-cli run stop "Dev server"

run rerun

unluminous-cli run rerun [name]

Stop a run and start it again, whatever state it was in.

[name]
The configuration. The chosen one when it is left out.
unluminous-cli run rerun

run select

unluminous-cli run select <name>

Choose which configuration the widget's play button, the Run menu and run start with no name all mean.

<name>
The configuration.
unluminous-cli run select "Dev server"

run output

unluminous-cli run output [name] [--tail <number>] [--wait-for <text>] [--timeout <milliseconds>]

What a run has written, as text. It ran in a pseudoterminal, so this is what it would have printed to a terminal — colors and progress bars included, with the escape sequences already read.

[name]
The configuration. The run that is showing when it is left out.
--tail <number>
Only the last so many lines.
--wait-for <text>
Wait until this text has been written before answering, which is how to wait for a server to say it is listening.
--timeout <milliseconds>
How long to wait for --wait-for. 10000 by default.
unluminous-cli run output --tail 20
unluminous-cli run output "Dev server" --wait-for "Listening on" --timeout 30000

run status

unluminous-cli run status [name]

Whether a run is going, and what it ended with: running, finished, stopped, or the exit code it chose.

[name]
The configuration. The chosen one when it is left out.
unluminous-cli run status --json
unluminous-cli run status "Dev server" --json

debug

The debugger: breakpoints, starting a session, stepping, the call stack, variables and expressions.

debug start

unluminous-cli debug start [name] [--wait-for-pause] [--timeout <milliseconds>]

Run a configuration under its debugger, showing the debug tile. The file that is open decides which debugger: its language names one, or the session refuses with a sentence saying what to install. Starting one replaces the session that was running.

[name]
The configuration. The chosen one when it is left out.
--wait-for-pause
Wait until the program stops somewhere before answering, so a script can set a breakpoint, start, and read a variable in three commands.
--timeout <milliseconds>
How long to wait for --wait-for-pause. 30000 by default.
unluminous-cli debug start
unluminous-cli debug start "Dev server" --wait-for-pause

debug stop

unluminous-cli debug stop

End the session: the polite request first, and a hard disconnect on a second stop or two seconds later. The debuggee's tab in the run tile stays, holding what it wrote.

unluminous-cli debug stop

debug continue

unluminous-cli debug continue [--wait-for-pause] [--timeout <milliseconds>]

Let the program run on to the next breakpoint.

--wait-for-pause
Wait until it stops again before answering.
--timeout <milliseconds>
How long to wait. 30000 by default.
unluminous-cli debug continue --wait-for-pause

debug step-over

unluminous-cli debug step-over [--wait-for-pause] [--timeout <milliseconds>]

Run the current line and stop on the next one, without going into any call it makes.

--wait-for-pause
Wait until it stops again before answering.
--timeout <milliseconds>
How long to wait. 30000 by default.
unluminous-cli debug step-over --wait-for-pause

debug step-into

unluminous-cli debug step-into [--wait-for-pause] [--timeout <milliseconds>]

Go into the call on the current line and stop at its first line.

--wait-for-pause
Wait until it stops again before answering.
--timeout <milliseconds>
How long to wait. 30000 by default.
unluminous-cli debug step-into --wait-for-pause

debug step-out

unluminous-cli debug step-out [--wait-for-pause] [--timeout <milliseconds>]

Finish the function the program is in and stop in whatever called it.

--wait-for-pause
Wait until it stops again before answering.
--timeout <milliseconds>
How long to wait. 30000 by default.
unluminous-cli debug step-out --wait-for-pause

debug run-to

unluminous-cli debug run-to <path> <line> [--wait-for-pause] [--timeout <milliseconds>]

Run until the program reaches a line, then stop there. A temporary breakpoint, a resume, and the breakpoint taken away again — which is how every debugger builds this.

<path>
The file, relative to the project or absolute.
<line>
The line, counting from 1.
--wait-for-pause
Wait until it stops before answering.
--timeout <milliseconds>
How long to wait. 30000 by default.
unluminous-cli debug run-to src/main.rs 42 --wait-for-pause

debug breakpoint

unluminous-cli debug breakpoint <add|remove|enable|disable|list|clear> [path] [line] [--condition <expression>] [--log <message>]

Where the program is to stop. add and remove take a file and a line; list prints every one in the project, with what the debugger said about it while a session is running. Breakpoints are kept in .unluminous/breakpoints.conf and move with the text as the file is edited.

<action>
add, remove, enable, disable, list, or clear.
[path]
The file. Not needed for list or clear.
[line]
The line, counting from 1.
--condition <expression>
Stop only while this is true. The debugger evaluates it, in the program's own language.
--log <message>
Print this instead of stopping, which is what other editors call a logpoint. The debugger formats it, so {name} reads a variable.
unluminous-cli debug breakpoint add src/main.rs 42
unluminous-cli debug breakpoint add src/main.rs 42 --condition "attempts > 3"
unluminous-cli debug breakpoint list --json
unluminous-cli debug breakpoint remove src/main.rs 42

debug frames

unluminous-cli debug frames [--include-subtle]

The call stack of the stopped thread, one frame a line: the function, the file and the line. Adapter-marked runtime frames are hidden unless --include-subtle asks for the complete stack. Answered from what the debugger has already been asked, so it costs nothing.

--include-subtle
Include adapter-marked runtime frames, which are normally hidden so the stack leads with application code.
unluminous-cli debug frames --json
unluminous-cli debug frames --include-subtle

debug variables

unluminous-cli debug variables [--frame <number>] [--expand <path>]

The variables of the frame that is showing. Only what has been read is printed, because a debugger reads a structure's contents only when somebody opens it; --expand asks for one row's children by name.

--frame <number>
Which frame, counting from 0 at the top. The one that is showing when it is left out.
--expand <path>
Read the children of this row and print them, naming it the way variables prints it — Locals/items.
unluminous-cli debug variables --json
unluminous-cli debug variables --expand Locals/items

debug set-value

unluminous-cli debug set-value <path> <value>

Change a variable in the running program. The answer is the value as the debugger now sees it, which is not always what was typed.

<path>
The row, as variables names it — Locals/count.
<value>
The new value, in the program's own language.
unluminous-cli debug set-value Locals/count 7

debug hover

unluminous-cli debug hover [--offset <bytes>] [--line <number>] [--column <number>] [--expression <text>] [--expand <path>] [--timeout <milliseconds>]

What a person sees when they rest the pointer on a name while the program is stopped: the expression Unluminous reads at that position, its value and type, and its children as a tree. Reads the name plus the field path in front of it, so a point on count in self.items.count asks about the whole of it. Unlike evaluate, the answer can be walked into with --expand.

--offset <bytes>
Ask about this position in the file rather than about the caret.
--line <number>
Ask about this line, counting from 1.
--column <number>
The column on that line. 1 when it is left out.
--expression <text>
Ask about this expression outright rather than about a position, which is how a value from evaluate is expanded.
--expand <path>
Open this row and read its children, naming it the way the rows are printed - self.items/0.
--timeout <milliseconds>
How long to wait for the debugger. 10000 by default.
unluminous-cli debug hover --line 42 --column 9 --json
unluminous-cli debug hover --expression self.items --expand self.items/0

debug set-expression

unluminous-cli debug set-expression <expression> <value>

Assign to whatever an expression names in the running program. The other half of set-value: that one names a row that has already been read, and this one names the target in the program's own language, so it reaches a value nothing has opened yet. A debugger that cannot compile an assignment still changes a plain variable it has already shown, and says so plainly when it can do neither.

<expression>
What to assign to, in the program's own language - self.items.count.
<value>
The new value, in the program's own language.
unluminous-cli debug set-expression self.items.count 7

debug evaluate

unluminous-cli debug evaluate <expression> [--timeout <milliseconds>]

Evaluate an expression in the frame that is showing. The debugger's own answer, or its own refusal.

<expression>
The expression. Everything after the verb is taken as it was typed, so it needs no quotes.
--timeout <milliseconds>
How long to wait for the answer. 10000 by default.
unluminous-cli debug evaluate items.len()

debug watch

unluminous-cli debug watch <add|remove|list> [expression]

Expressions re-evaluated at every stop. add and remove take one; list prints them with their last answers.

<action>
add, remove, or list.
[expression]
The expression, for add and remove.
unluminous-cli debug watch add attempts
unluminous-cli debug watch list --json

debug output

unluminous-cli debug output [--tail <number>]

What the debugger itself has said: what it loaded, what it could not find, and why it refused something. Not the program's own output, which goes to the run tile and is read with run output.

--tail <number>
Only the last so many lines.
unluminous-cli debug output --tail 20

debug status

unluminous-cli debug status [--wait-for-pause] [--timeout <milliseconds>]

Whether a session is running and what it is doing: starting, running, paused with the file and line it stopped at, or ended with the code the program chose.

--wait-for-pause
Wait until the program stops before answering, which is how a script waits for a breakpoint it has already set.
--timeout <milliseconds>
How long to wait. 30000 by default.
unluminous-cli debug status --json
unluminous-cli debug status --wait-for-pause

debug adapters

unluminous-cli debug adapters

Which debuggers this Unluminous drives, where each one is on this machine, what is missing, and the command that installs it. The first thing to run when a debug session will not start: it answers in fields under --json, so nothing has to be guessed at from a refusal.

unluminous-cli debug adapters
unluminous-cli debug adapters --json

debug install

unluminous-cli debug install <lldb|node>

Install a debug adapter by running its own install command in the run tile, where it can be watched with run output and stopped. Unluminous itself downloads nothing: what runs is a package manager, or an editor's extension installer, named by debug adapters.

<adapter>
Which debugger: lldb or node.
unluminous-cli debug install lldb

git

What git says about the project, its branches, and every entry on the Git menu.

git status

unluminous-cli git status

What the machine's real git says about the project: the branch, whether a merge or rebase is unfinished, and what the last command returned, using the same credentials, SSH agent, configuration and hooks as the terminal. Git is read again when this is asked, so a branch switched or a file changed in a terminal a moment ago is in the answer.

unluminous-cli git status --json

git actions

unluminous-cli git actions

Everything on the Git menu, by the name git action takes.

unluminous-cli git actions --json

git action

unluminous-cli git action <name> [--path <path>] [--wait <milliseconds>]

Run one of the entries on the Git menu. Git runs on a thread, so the answer says it was asked for, and --wait holds on for what came back.

<name>
The entry, such as commit, push, pull, fetch, branches or annotate.
--path <path>
The file it is about. The file that is showing when it is left out.
--wait <milliseconds>
Wait up to this long for git to answer before returning.
unluminous-cli git action fetch --wait 20000
unluminous-cli git action annotate
unluminous-cli git action show-history --path README.md

git branches

unluminous-cli git branches

The branches of the project, saying which one is checked out and which live on a remote. This is what the branch button in the title bar lists, read from the status git already reported rather than by running a git command.

unluminous-cli git branches --json

git switch

unluminous-cli git switch <branch> [--wait <milliseconds>]

Move to a branch that already exists, which is what choosing one from the title bar's branch button does. It goes through the machine's real git on a thread, so uncommitted work that would be overwritten stops it with git's own message rather than being discarded; git action new-branch is how a branch is started.

<branch>
The branch to move to, as git branches names it.
--wait <milliseconds>
Wait up to this long for git to answer before returning.
unluminous-cli git switch main --wait 20000

realm

The Realm: realm files, nodes, connections, the camera, and driving each kind of node.

realm show

unluminous-cli realm show

Show the Realm, the canvas of nodes, and give it the keyboard.

unluminous-cli realm show

realm hide

unluminous-cli realm hide

Put the canvas away. Everything running on it keeps running.

unluminous-cli realm hide

realm here

unluminous-cli realm here [--node <node>]

Which node this command is running inside, what that node is wired to, and the command that drives each of them. Run this **first** when UNLUMINOUS_REALM_NODE is set in your environment: it is the one command that answers where you are, because the answer depends on which process is asking. Outside a node it says so and says what that means — every node is reachable and no --from is needed, which is the window's own agent.

--node <node>
Answer about this node rather than the one this process is in. Filled in from UNLUMINOUS_REALM_NODE when it is not given, which is the ordinary case and needs nothing.
unluminous-cli realm here
unluminous-cli realm here --json

realm view

unluminous-cli realm view

The realm that is open, as data: its file, whether it can be changed, every node with its kind, its title, where it is and how big it is, and every connection. This is what to read before acting on a node, because everything else here names one by the id this prints.

unluminous-cli realm view --json

realm nodes

unluminous-cli realm nodes

The nodes on the realm that is open, one a line: id, kind, title, place, size, and what each is connected to.

unluminous-cli realm nodes

realm manage

unluminous-cli realm manage

Open the modal listing every realm file in this project, with a search box. realm list is the same list as data.

unluminous-cli realm manage

realm list

unluminous-cli realm list

Every .realm file in this project, which one is open and how many nodes each holds.

unluminous-cli realm list --json

realm open

unluminous-cli realm open <realm>

Show a realm file in the panel, in a tab of its own. One realm is open at a time.

<realm>
The realm's name, or its path in the project.
unluminous-cli realm open architecture
unluminous-cli realm open .realm-files/architecture.realm

realm close

unluminous-cli realm close [realm]

Close a realm's tab on the bar. The file stays; realm open reopens it.

[realm]
The realm's name, or its path in the project. The open one when it is not given.
unluminous-cli realm close Scratch

realm files

unluminous-cli realm files [--show] [--hide]

Realm files newest first, and which are tabs. --show opens the bar's folder list.

--show
Open the list.
--hide
Close it.
unluminous-cli realm files --json

realm new

unluminous-cli realm new [name]

Make an empty realm in .realm-files/ and open it. Refused when a realm by that name is already there, because nothing is ever written over.

[name]
What to call it. Realm when it is not given.
unluminous-cli realm new Architecture

realm rename

unluminous-cli realm rename <realm> <name>

Rename a realm's file. What this machine remembers about it goes with it.

<realm>
The realm's name, or its path in the project.
<name>
What to call it.
unluminous-cli realm rename main Architecture

realm duplicate

unluminous-cli realm duplicate [realm]

Copy a realm to <name> copy.realm beside it, every node and connection under new ids, and open the copy. The nodes are copies: a terminal on the copy is a second terminal rather than a second drawing of one.

[realm]
The realm's name, or its path in the project. The open one when it is not given.
unluminous-cli realm duplicate main

realm delete

unluminous-cli realm delete [realm]

Delete a realm's file the way the explorer deletes one, to the Recycle Bin on Windows, with what this machine remembered about it. When it was the open one, another realm opens.

[realm]
The realm's name, or its path in the project. The open one when it is not given.
unluminous-cli realm delete Scratch

realm import

unluminous-cli realm import

Turn .unluminous/space.conf, where the canvas was kept before realm files, into one .realm file a view under .realm-files/. Nothing is deleted and nothing is written over: a realm file that is already there is left alone and named in the answer. A project is imported once by itself the first time it opens; this is the same conversion by hand.

unluminous-cli realm import

realm info

unluminous-cli realm info

What the open realm's file says about which Unluminous may read and write it: its format, the reader and writer it needs, the features it needs, whether it can be changed here and why not, how many nodes it holds, and the kinds of node on it this Unluminous does not know. This is how to find out why a realm is read only.

unluminous-cli realm info --json

realm add

unluminous-cli realm add <terminal|browser|folder|editor|chat|tasks|image|audio|video|note|shape> [file] [--x <points>] [--y <points>] [--width <points>] [--height <points>] [--title <text>] [--command <text>] [--url <address>] [--root <path>] [--path <path>] [--text <words>]

Put a node on the realm that is open and answer with its id. A terminal node starts the machine's own shell in the project folder, or the program named by --command, with unluminous-cli on its PATH and pointed at this window, UNLUMINOUS_REALM_NODE set to its id so an agent started in it knows which node it is, UNLUMINOUS_REALM_HINT saying what to run first, and UNLUMINOUS_CLI and UNLUMINOUS_INSTANCE for a program that wants the path and the window outright. An image, audio or video node shows a file in this project, named as the second argument; a note node makes a Markdown file of that name in .realm-files/<realm>/, or shows an existing .md file when it is given one. A shape node is the shape named as the second argument, with --text for its words.

<kind>
terminal, browser, folder, editor, chat, tasks, image, audio, video, note or shape.
[file]
An image, audio or video node: the file in this project it shows. A note node: a name for a new note, or the path of an existing .md file. A shape node: which shape.
--x <points>
Where to put it, in canvas points. The middle of what is showing when it is not given.
--y <points>
The same, down the canvas.
--width <points>
How wide, in canvas points.
--height <points>
How tall.
--title <text>
What the header says. Empty means call it after what it holds.
--command <text>
A terminal node: the program to run instead of the shell.
--url <address>
A browser node: the page to open.
--root <path>
A folder node: which folder to show. The project when it is not given.
--path <path>
An editor node: which file to open.
--text <words>
A shape node: its words.
unluminous-cli realm add terminal --command claude
unluminous-cli realm add shape diamond --text Decide
unluminous-cli realm add browser --url https://example.com/
unluminous-cli realm add editor --path src/main.rs --x 900 --y 40
unluminous-cli realm add image design/cover.png
unluminous-cli realm add note Plan

realm move

unluminous-cli realm move <node> [--x <points>] [--y <points>]

Move a node to a place on the canvas, in canvas points.

<node>
The node's id, from realm list.
--x <points>
Where its left hand edge goes.
--y <points>
Where its top edge goes.
unluminous-cli realm move 7 --x 320 --y 180

realm size

unluminous-cli realm size <node> [--width <points>] [--height <points>]

Resize a node. It is never made smaller than its kind allows, and the reply says what size it really came out.

<node>
The node's id.
--width <points>
How wide.
--height <points>
How tall.
unluminous-cli realm size 7 --width 900 --height 520

realm title

unluminous-cli realm title <node> <title>

Call a node something else. An empty name puts it back to being called after what it holds.

<node>
The node's id.
<title>
What the header says.
unluminous-cli realm title 7 the agent

realm remove

unluminous-cli realm remove <node>

Take a node off the canvas, stopping whatever was running in it. A file editor node's tab is closed, which writes it first if it was edited.

<node>
The node's id.
unluminous-cli realm remove 7

realm focus

unluminous-cli realm focus <node>

Choose a node and give it the keyboard. It stays where it is in the stacking order, as it does when it is clicked; realm arrange moves it.

<node>
The node's id.
unluminous-cli realm focus 7

realm arrange

unluminous-cli realm arrange <node> <front|forward|backward|back>

Move a node in the stacking order, which is what the node menu's Arrange rows do: front puts it over every other node, forward and backward move it one place, back puts it behind every other node. The order is written to the realm file.

<node>
The node's id.
<how>
front, forward, backward or back.
unluminous-cli realm arrange 7 back
unluminous-cli realm arrange 3 forward

realm connect

unluminous-cli realm connect <from> <to> [--pipe <lines>] [--from-point <point>] [--to-point <point>]

Wire one node's output to another's input. A connection is what lets an agent in a terminal node act on the node it is wired to; with --pipe lines it also types each line the first node's program writes into the second node's terminal. A shape is joined at the point --from-point or --to-point names, or the one nearest the other node.

<from>
The node the wire leaves.
<to>
The node it arrives at.
--pipe <lines>
Carry text as well as permission. Only into a terminal node, because only a terminal has an input to type into.
--from-point <point>
top, right, bottom or left; point-1 to point-5 on a star.
--to-point <point>
The same, where it arrives.
unluminous-cli realm connect 7 9
unluminous-cli realm connect 7 9 --pipe lines

realm disconnect

unluminous-cli realm disconnect <connection>

Take a connection away, by its id from realm connections.

<connection>
The connection's id.
unluminous-cli realm disconnect 12

realm connections

unluminous-cli realm connections [--from <node>]

Every connection on the view that is showing: its id, which node it leaves, which it arrives at, and whether it carries lines. --from narrows it to one node's own, which is what an agent in a terminal node asks to find out what it may act on.

--from <node>
Only the connections leaving this node.
unluminous-cli realm connections --from 7

realm camera

unluminous-cli realm camera [--x <points>] [--y <points>] [--zoom <factor>] [--fit]

Pan and zoom the canvas. With --fit it moves so that every node is on the screen at once, which is how to find something that has been dragged out of sight.

--x <points>
The canvas point drawn at the top left corner.
--y <points>
The same, down the canvas.
--zoom <factor>
How many screen points one canvas point is, from 0.25 to 2.5.
--fit
Put every node on the screen at once.
unluminous-cli realm camera --fit
unluminous-cli realm camera --zoom 0.5

realm send

unluminous-cli realm send <node> <text> [--from <node>]

Type a line into a terminal node and press Enter. --from says which node is asking, and a node may only send to a node it is wired to; with no --from it is the window's own and may reach any of them.

<node>
The terminal node to type into.
<text>
The line to type.
--from <node>
Which node is asking. It must be wired to the one it names.
unluminous-cli realm send 9 cargo test
unluminous-cli realm send 9 cargo test --from 7

realm read

unluminous-cli realm read <node> [--tail <lines>]

Read what a terminal node is showing: the scrollback as well as the screen, so the commands that have scrolled above the fold are in it. This is what terminal read is for the terminal panel, and it is the way to check what a node printed, what it came back showing after a project was reopened, and what an agent running in a node has said.

<node>
The terminal node's id.
--tail <lines>
Answer with only the last N lines.
unluminous-cli realm read 7
unluminous-cli realm read 7 --tail 40

realm chat

unluminous-cli realm chat <node> <new|send|stop|state|messages|last|attach|providers|use|history|open|remove|tools|view> [words] [--from <node>]

Drive an Agent Chat node's own conversation: new, send, stop, state, messages, last, attach, providers, use, history, open, remove, tools, view and the component verbs, which are the same verbs plugins run agent-chat has and reach the same code. The difference is whose conversation: each chat node holds one of its own, where plugins run agent-chat drives the pane's. Like the pane's, send does not wait - state says when the answer has arrived.

<node>
The chat node's id, from realm list.
<verb>
What to do: new, send, stop, state, messages, last, attach, providers, use, history, open, remove, tools or view.
[words]
What the verb takes: the message for send, the conversation id for open, on or off for tools. It is the rest of the line, so a message needs no quoting.
--from <node>
Which node is asking. It must be wired to the one it names.
unluminous-cli realm chat 7 state
unluminous-cli realm chat 7 send Summarize what this project does
unluminous-cli realm chat 7 last --json

realm restart

unluminous-cli realm restart <node> [--resume] [--running]

Start a terminal node's program again in the same folder. With --resume it starts the agent on the conversation it named, which Claude takes and Codex does not. With --running it types the program the node was last seen running into the shell it already has, which is what a node comes back as when somebody typed an agent into a plain terminal rather than giving the node a command.

<node>
The terminal node's id.
--resume
Start the agent on the session it named, rather than a fresh one.
--running
Type what the node was last seen running into its shell, continuing an agent's most recent conversation in that folder. What is recorded is a program name rather than a command line, so its arguments are not restored.
unluminous-cli realm restart 7 --resume
unluminous-cli realm restart 7 --running

realm font

unluminous-cli realm font <node> [--size <points>] [--bigger] [--smaller] [--reset]

How big a terminal node's letters are. The ticket this canvas comes from asks for a size a node keeps for itself, so a node that has been given one follows it and one that has not follows terminal.font.size. With no flag at all it answers the size the node is drawn at.

<node>
The terminal node's id.
--size <points>
Any size from 6 to 96, which is what terminal.font.size itself takes.
--bigger
One step up the list the Settings window offers.
--smaller
One step down it.
--reset
Follow the terminal's own setting again.
unluminous-cli realm font 7 --size 16
unluminous-cli realm font 7 --smaller

realm zoom

unluminous-cli realm zoom <node> [--factor <number>] [--bigger] [--smaller] [--reset] [--from <node>]

How big one node draws what it holds. Each kind walks the number that really decides its size: a terminal and a file editor a point size, a folder view, an agent chat and the tasks board a multiplier over everything they draw, and a web browser the page's own zoom. With no flag at all it answers the factor the node is drawn at. This is what the modifier wheel over a node does, and it changes nothing about the canvas's own zoom, which is realm camera.

<node>
The node's id.
--factor <number>
How big, as a multiplier for a folder, a chat, the board or a browser, or a point size for a terminal or an editor.
--bigger
One step up.
--smaller
One step down.
--reset
Back to the size the window's own setting gives.
--from <node>
Which node is asking. It must be wired to the one it names.
unluminous-cli realm zoom 7 --bigger
unluminous-cli realm zoom 9 --factor 1.5

realm address

unluminous-cli realm address <node> <url> [--from <node>]

Type an address into a browser node's own address bar and enter it, which is what pressing Enter in that field does. realm browser <node> go is the same navigation asked for directly; this exists so the control a person uses has a way in of its own.

<node>
The browser node's id.
<url>
The address, or a path to a local page in this project.
--from <node>
Which node is asking. It must be wired to the one it names.
unluminous-cli realm address 9 https://example.com/

realm browser

unluminous-cli realm browser <node> <go|back|forward|reload|url|shot|pick|pin|unpin|pinned> [--url <address>] [--selector <css>] [--from <node>] [--path <file>]

Drive a browser node: go to an address, back, forward, reload, url to read where it is, and shot to write a picture of the node to a file. pin --selector <css> makes the node show only that element of the page, scaled to fill the node without being stretched; unpin shows the whole page again; pinned says what is pinned; pick opens the element picker in the page for a person to click an element, which is what Select Element on the page's right click menu does. A pin belongs to the address it was made on and is kept in the realm file. A window renders one page at a time, so the node acted on is shown first. **shot photographs the node as Unluminous drew it and not the page inside it**: a rendered page is a native child window the operating system composites on top, and no picture taken from inside Unluminous contains one. Use it to see the node, its address bar and where it is on the canvas; use url to read the address, and the agent's own tools to read what a page says.

<node>
The browser node's id.
<command>
go, back, forward, reload, url, shot, pick, pin, unpin or pinned.
--url <address>
Where to go, for go.
--selector <css>
Which element to show, for pin.
--from <node>
Which node is asking. It must be wired to the one it names.
--path <file>
Where to write the picture, for shot.
unluminous-cli realm browser 9 go --url https://example.com/ --from 7
unluminous-cli realm browser 9 url
unluminous-cli realm browser 9 pin --selector "main table.prices"
unluminous-cli realm browser 9 unpin

realm folder

unluminous-cli realm folder <node> <expand|collapse|select|open|root|rows> [--path <path>] [--from <node>]

Drive a folder node: expand and collapse a folder in it, select a row, open a file, root to point it at another folder, and rows to read what it is showing. open puts the file in a File Editor node wired to this one, made if there is none, as a click does. root is what the node's own Choose Folder... menu row calls, so several folder nodes can show several different folders.

<node>
The folder node's id.
<command>
expand, collapse, select, open, root or rows.
--path <path>
Which row, or which folder for root.
--from <node>
Which node is asking. It must be wired to the one it names.
unluminous-cli realm folder 11 expand --path crates/unluminous-app --from 7
unluminous-cli realm folder 11 rows

realm editor

unluminous-cli realm editor <node> <path> [--from <node>]

Put a file in a file editor node. A file already open somewhere else is moved into the node rather than opened twice, because two tabs on one file would be two documents over one path.

<node>
The editor node's id.
<path>
The file, relative to the project or absolute.
--from <node>
Which node is asking. It must be wired to the one it names.
unluminous-cli realm editor 13 src/main.rs --from 7

realm note

unluminous-cli realm note <view> <node> <raw|side|preview> [--from <node>]

Show a note node as its Markdown source (raw), as the source beside its preview (side), or as the preview alone (preview). The same three buttons are at the right of the note's header. The view is written in the realm file, because it is how the note is meant to be read.

<command>
view.
<node>
The note node's id.
<view>
raw, side or preview.
--from <node>
Which node is asking. It must be wired to the one it names.
unluminous-cli realm note view 13 preview

realm shape

unluminous-cli realm shape <node> [view|text|colour|align|valign|size|kind|edit|done|pick|points] [value]

Change a whiteboard shape, as its menu and a double click do: text (\n is a new line), color (#RRGGBBAA, or theme), align, valign, size (points, larger or smaller), kind, edit and done typing, pick the color picker (then a color, apply or cancel), and points.

<node>
The shape node's id.
[command]
What to change.
[value]
What the command takes.
unluminous-cli realm shape 12 text Agent builds it
unluminous-cli realm shape 12 color #FFC062D2

realm play

unluminous-cli realm play <node> [--from <node>]

Play an audio or video node, and answer where it is and how long it is. Sounds play at once; one video plays at a time, in the window's web view.

<node>
The audio or video node's id.
--from <node>
Which node is asking. It must be wired to the one it names.
unluminous-cli realm play 13

realm pause

unluminous-cli realm pause <node> [--from <node>]

Pause an audio or video node. Where it stopped is remembered on this machine.

<node>
The audio or video node's id.
--from <node>
Which node is asking. It must be wired to the one it names.
unluminous-cli realm pause 13

realm seek

unluminous-cli realm seek <node> <seconds> [--from <node>]

Move an audio or video node to a time, in seconds from the start.

<node>
The audio or video node's id.
<seconds>
How far in, in seconds.
--from <node>
Which node is asking. It must be wired to the one it names.
unluminous-cli realm seek 13 42.5

realm volume

unluminous-cli realm volume <node> <level> [--from <node>]

Set how loud an audio or video node plays, from 0 to 1. Written in the realm file.

<node>
The audio or video node's id.
<level>
From 0 to 1.
--from <node>
Which node is asking. It must be wired to the one it names.
unluminous-cli realm volume 13 0.5

plugins

The plugins, their panes and tabs, and each plugin's own commands, such as Agent Chat's and Agent Tasks'.

plugins list

unluminous-cli plugins list

The plugins Unluminous has, which of them are switched on, and what each one claims: a language it colors, or a pane, a tab, a menu and a Settings page it contributes. They ship with Unluminous; nothing is fetched.

unluminous-cli plugins list --json

plugins install

unluminous-cli plugins install <id>

Write a plugin out into the settings folder, so its files can be read and changed.

<id>
The plugin's id, as plugins list gives it.
unluminous-cli plugins install rust

plugins enable

unluminous-cli plugins enable <id>

Switch a plugin on, so it colors the files it claims.

<id>
The plugin's id.
unluminous-cli plugins enable rust

plugins disable

unluminous-cli plugins disable <id>

Switch a plugin off. Its files stay where they are.

<id>
The plugin's id.
unluminous-cli plugins disable rust

plugins show

unluminous-cli plugins show <id>

One plugin in full: its manifest, whether it describes a language or draws, what it contributes, and every command it answers.

<id>
The plugin's id, as plugins list gives it.
unluminous-cli plugins show agent-tasks --json

plugins reload

unluminous-cli plugins reload

Read every plugin manifest from disk again, so one changed by hand takes effect with no restart. One that will not parse is skipped with its reason.

unluminous-cli plugins reload --json

plugins pane

unluminous-cli plugins pane <pane> [--show] [--hide] [--side <side>]

Show, hide or move a pane a plugin contributed: what its rail button and a drag on its header do. A plugin's id names its pane: designer, agent-tasks, agent-chat, database.

<pane>
The plugin's id, or <plugin id>/<pane id>.
--show
Show it, building the plugin's own state the first time.
--hide
Put it away.
--side <side>
Dock it to left, right, top or bottom.
unluminous-cli plugins pane agent-tasks/board --show
unluminous-cli plugins pane designer --show
unluminous-cli plugins pane agent-tasks/board --side bottom

plugins tab

unluminous-cli plugins tab <tab> [--open] [--close]

Open or close a plugin's own tab in the editing area: a tab with no file behind it.

<tab>
The tab, as <plugin id>/<tab id> — agent-tasks/board.
--open
Open it, or show it if it is already open.
--close
Close it.
unluminous-cli plugins tab agent-tasks/board --open

plugins run

unluminous-cli plugins run <id> <command> [arguments]

Run one of a plugin's own commands, down the same path its menu entry and its buttons take. plugins show lists them.

<id>
The plugin's id.
<command>
The command, as plugins show lists it.
[arguments]
The rest of the line, handed to the command as it stands.
unluminous-cli plugins run agent-tasks board --json
unluminous-cli plugins run agent-tasks new-task Rewrite the importer
unluminous-cli plugins run agent-tasks start task-27
unluminous-cli plugins run database tables public --json
unluminous-cli plugins run database query select count(*) from member
unluminous-cli plugins run database new-table public.shelf id:integer:pk title:text:notnull
unluminous-cli plugins run database set 1 title Kind of Green
unluminous-cli plugins run database submit
unluminous-cli plugins run designer open Landing page

plugins view

unluminous-cli plugins view <id>

What a plugin's pane holds, as data rather than pixels: for Agent-Tasks the sprint, the four lanes, their counts and their cards. A screenshot cannot answer how many tickets are in progress; this can.

<id>
The plugin's id.
unluminous-cli plugins view agent-tasks --json

notebook

Notebooks: cells, running them in a kernel, outputs, variables and exports.

notebook status

unluminous-cli notebook status [--path <file>]

The notebook that is showing: its kernel and whether it is idle or busy, the chosen cells, and every cell's number, id, kind, execution count, run state, first line and outputs.

--path <file>
A notebook to open first, rather than the tab that is showing.
unluminous-cli notebook status
unluminous-cli notebook status --path analysis.ipynb --json

notebook cell

unluminous-cli notebook cell [cell] [--id <id>] [--path <file>] [--pictures <folder>]

One cell's source and its outputs as text: streams, results, the traceback, tables as rows. A picture is written to a PNG file and its path given.

[cell]
The cell's number, counting from 1. The chosen cell when it is left out.
--id <id>
The cell's id instead of its number.
--path <file>
A notebook to open first.
--pictures <folder>
Where to write picture outputs. The temporary folder when it is left out.
unluminous-cli notebook cell 3
unluminous-cli notebook cell --id 4f2a9c01 --json

notebook run

unluminous-cli notebook run [cell] [--id <id>] [--to <cell>] [--all] [--above] [--below] [--wait] [--debug] [--timeout <ms>] [--path <file>]

Run cells in a live kernel started from the project's Python: one cell, a range, above, below or all. A run stops at the first cell that raises. --wait answers when it has finished, with every cell's outputs.

[cell]
The cell to run, counting from 1. The chosen cell when it is left out.
--id <id>
The cell's id instead of its number.
--to <cell>
Run from the cell through this one.
--all
Run every cell, from the top.
--above
Run every cell above the cell, not the cell itself.
--below
Run the cell and every cell below it.
--wait
Answer when the run has finished, with the outputs.
--debug
Debug the cell instead: it stops at its breakpoints, or on its first line when it has none, and the debug commands carry on from there.
--timeout <ms>
How long --wait waits, in milliseconds. Ten minutes when it is left out.
--path <file>
A notebook to open first.
unluminous-cli notebook run 2 --wait
unluminous-cli notebook run --all --wait --timeout 120000
unluminous-cli notebook run 4 --below

notebook add

unluminous-cli notebook add [source] [--kind <kind>] [--at <position>] [--path <file>]

Add a cell, with its source if one is given, and choose it. Below the chosen cell when no position is given. One undo step.

[source]
The new cell's source. Use \n for a line break inside it.
--kind <kind>
code, markdown or raw. Code when it is left out.
--at <position>
Where the new cell goes, counting from 1: 1 puts it first, one more than the number of cells puts it last.
--path <file>
A notebook to open first.
unluminous-cli notebook add print(42)
unluminous-cli notebook add --kind markdown --at 1 "# Results"

notebook source

unluminous-cli notebook source <source> [--cell <number>] [--id <id>] [--path <file>]

Replace a cell's source, keeping its id and kind. Its outputs stay until it is run again. One undo step.

<source>
The cell's new source. Use \n for a line break inside it.
--cell <number>
The cell, counting from 1. The chosen cell when it is left out.
--id <id>
The cell's id instead of its number.
--path <file>
A notebook to open first.
unluminous-cli notebook source --cell 2 df.describe()

notebook edit

unluminous-cli notebook edit <delete|move|kind|merge|split|copy|cut|paste|duplicate|comment|tags|clear|clear-all> [--cell <number>] [--id <id>] [--to <number>] [--kind <kind>] [--above] [--tags <words>] [--path <file>]

Change cells as a whole: delete, move, change kind, merge, split at a line, copy, cut, paste, duplicate, comment out, tag, clear outputs. Each is one undo step, as from the Notebook menu.

<operation>
delete, move, kind, merge, split, copy, cut, paste, duplicate, comment, tags, clear or clear-all.
--cell <number>
The cell, counting from 1. The chosen cell when it is left out.
--id <id>
The cell's id instead of its number.
--to <number>
For move, the position it goes to. For merge, the last cell merged. For split, the line of the cell that starts the new cell, counting from 1.
--kind <kind>
For kind: code, markdown or raw.
--above
For paste, paste above the cell rather than below it.
--tags <words>
For tags, the cell's tags separated by commas. Left out, the cell's tags are taken away.
--path <file>
A notebook to open first.
unluminous-cli notebook edit delete --cell 3
unluminous-cli notebook edit tags --cell 2 --tags parameters,slow
unluminous-cli notebook edit move --cell 5 --to 1
unluminous-cli notebook edit kind --cell 2 --kind markdown
unluminous-cli notebook edit split --cell 4 --to 3

notebook select

unluminous-cli notebook select [cell] [--to <cell>] [--edit] [--section <direction>] [--path <file>]

Choose cells, which is what every Notebook menu entry and action run notebook-... acts on. In command mode unless --edit puts the caret in the cell. --section goes to the next or previous Markdown heading.

[cell]
The first cell to choose, counting from 1. Needed unless --section is given.
--to <cell>
Choose every cell from the first through this one.
--edit
Put the caret at the start of the cell, in edit mode.
--section <direction>
next or previous: choose the next or previous cell that starts with a heading.
--path <file>
A notebook to open first.
unluminous-cli notebook select 3
unluminous-cli notebook select 2 --to 4

notebook view

unluminous-cli notebook view <collapse|collapse-output|collapse-section|render|line-numbers|variables> [--cell <number>] [--id <id>] [--path <file>]

Show or hide part of a notebook: collapse a cell, its outputs, or the section under a heading, render or edit a Markdown cell, and switch line numbers and the Variables panel. Each one switches back when it is given again.

<operation>
collapse, collapse-output, collapse-section, render, line-numbers or variables.
--cell <number>
The cell, counting from 1. The chosen cell when it is left out.
--id <id>
The cell's id instead of its number.
--path <file>
A notebook to open first.
unluminous-cli notebook view collapse-section --cell 1
unluminous-cli notebook view line-numbers

notebook output

unluminous-cli notebook output <sort|traceback|scroll|open> [--cell <number>] [--id <id>] [--column <number>] [--descending] [--line <number>] [--output <number>] [--path <file>]

Do what a person does to an output with the pointer: sort a table by a column, open or close a traceback, scroll a tall output to a line, or open an HTML or SVG output in a browser tab.

<operation>
sort, traceback, scroll or open.
--cell <number>
The cell, counting from 1. The chosen cell when it is left out.
--id <id>
The cell's id instead of its number.
--column <number>
For sort, the column, counting from 1. Left out, the table goes back to its own order.
--descending
For sort, largest first.
--line <number>
For scroll, the line to put at the top, counting from 1.
--output <number>
For open, which output, counting from 1. The first when it is left out.
--path <file>
A notebook to open first.
unluminous-cli notebook output sort --cell 4 --column 2 --descending
unluminous-cli notebook output traceback --cell 6

notebook outline

unluminous-cli notebook outline [--go <number>] [--path <file>]

The notebook's outline: every Markdown heading, set in by its level, and every code cell by its first line. --go goes to one of them.

--go <number>
Go to this entry of the outline, counting from 1.
--path <file>
A notebook to open first.
unluminous-cli notebook outline
unluminous-cli notebook outline --go 3

notebook kernel

unluminous-cli notebook kernel [status|start|interrupt|restart|shut-down|pythons|kernels|choose|install|install-rust] [--python <path>] [--name <kernelspec>] [--path <file>]

The kernel: start, interrupt, restart, shut down; list this machine's Pythons and whether each has ipykernel, or a Python's kernels; choose the Python or kernelspec (--name rust runs the cells as Rust); install ipykernel, or install-rust to build and register evcxr, the Rust kernel, in the run tile. No Jupyter server is needed.

[operation]
status, start, interrupt, restart, shut-down, pythons, kernels, choose, install or install-rust. status when it is left out.
--python <path>
For choose and kernels, the Python's path.
--name <kernelspec>
For choose, the kernelspec to run, as kernels lists it.
--path <file>
A notebook to open first.
unluminous-cli notebook kernel pythons
unluminous-cli notebook kernel choose --python C:/work/.venv/Scripts/python.exe
unluminous-cli notebook kernel choose --name rust
unluminous-cli notebook kernel install-rust
unluminous-cli notebook kernel restart

notebook complete

unluminous-cli notebook complete [--cell <number>] [--id <id>] [--line <number>] [--column <number>] [--limit <number>] [--choose <name>] [--path <file>]

What the completion popup offers at a place in a code cell: the names the live kernel knows, such as a DataFrame's columns after df. or a Vec's methods after v., beside the notebook's own words, best first. Waits for the kernel's answer. --choose applies a row as Enter would.

--cell <number>
The cell, counting from 1. The caret's place when neither --cell nor --line is given.
--id <id>
The cell's id instead of its number.
--line <number>
The line within the cell, counting from 1. The end of the cell when it is left out.
--column <number>
The column on that line, counting from 1. The end of the line when it is left out.
--limit <number>
Print at most this many rows. 50 when it is left out, and 0 means all of them.
--choose <name>
Apply this row, by its name, as Enter would.
--path <file>
A notebook to open first.
unluminous-cli notebook complete --cell 2 --line 1
unluminous-cli notebook complete --cell 3 --choose describe --json

notebook variables

unluminous-cli notebook variables [--path <file>]

The variables the kernel holds: name, type, the start of the value, and shape or length. A Rust kernel gives names and types only.

--path <file>
A notebook to open first.
unluminous-cli notebook variables --json

notebook input

unluminous-cli notebook input <value> [--path <file>]

Answer the input() a running cell is waiting on. notebook status says when one is waiting and what it asked.

<value>
What to answer with.
--path <file>
A notebook to open first.
unluminous-cli notebook input yes

notebook export

unluminous-cli notebook export <html|md|py|rs> [--to <file>] [--path <file>]

Write the notebook as HTML with its outputs, Markdown with pictures beside it, Python with # %% cells, or Rust with // %% cells. Beside the notebook unless --to says where.

<format>
html, md, py or rs.
--to <file>
Where to write it.
--path <file>
A notebook to open first.
unluminous-cli notebook export html
unluminous-cli notebook export py --to analysis.py

notebook new

unluminous-cli notebook new [path] [--language <language>]

Make a new notebook with one empty code cell and open it. Untitled.ipynb in the project folder when no path is given. --language rust makes a Rust notebook, run by evcxr.

[path]
Where to make it, relative to the project folder.
--language <language>
python or rust. python when it is left out.
unluminous-cli notebook new
unluminous-cli notebook new analysis/explore.ipynb
unluminous-cli notebook new scratch.ipynb --language rust

notebook convert

unluminous-cli notebook convert <path>

Write a .py file's # %% cells into a notebook beside it, or a notebook into a .py file, and open it. Nothing is written over.

<path>
The .py or .ipynb file to convert.
unluminous-cli notebook convert script.py
unluminous-cli notebook convert analysis.ipynb

modal

Dialogs: open one, type into its box, read its results, choose and accept.

action

Every menu entry, by name: list them, find one, run one.

action list

unluminous-cli action list [--menu <name>]

Every entry on every menu, with the name action run takes, the menu it is on, its keyboard shortcut and whether it can be used just now. A new menu entry appears here without anybody adding it. Ask for one menu with --menu and the answer is only that menu.

--menu <name>
Only the entries on this menu, by the name it is shown under; submenus name their own rows. Several, comma-separated, for more than one. Every menu when it is left out.
unluminous-cli action list --json
unluminous-cli action list --menu view --json

action find

unluminous-cli action find [text] [--limit <number>]

Menu entries whose wording matches some text, best first - the Find Action palette's own list as data. Use it rather than reading all of action list when you roughly know the name: the letters match as a subsequence, so tln finds Toggle Line Numbers, and the menu counts, so git commit finds Commit.

[text]
What to look for. Every entry, in menu order, when it is left out.
--limit <number>
Print at most this many rows. 20 when it is left out, and 0 means all of them.
unluminous-cli action find line numbers --json
unluminous-cli action find comment --json

action run

unluminous-cli action run <name> [--path <path>]

Run a menu entry by name. This is the way to reach something with no command of its own; the entries that would open a file chooser are refused, and the answer says which command to use instead.

<name>
The entry, as action list gives it, such as toggle-line-numbers.
--path <path>
The file or folder the entry is about, for the ones that take one.
unluminous-cli action run toggle-line-numbers
unluminous-cli action run about

panel

Where each panel is docked, how large it is, and its zoom.

panel list

unluminous-cli panel list

Every panel Unluminous has — the explorer, the terminal, the run tile and the debug tile — which edge of the window each is docked to, where in that edge, how big it is, whether it is showing, and the rectangle it occupies on screen. A pane a plugin contributes is listed by plugins list and can be sized and docked by name here.

unluminous-cli panel list --json

panel dock

unluminous-cli panel dock <panel> <left|right|top|bottom> [--position <number>] [--fill]

Move a panel to an edge of the window: the same change dragging its header makes. A side can hold more than one panel, side by side, so the terminal can sit beside the explorer down the left.

<panel>
explorer, terminal, run, debug, or a contributed pane's <plugin>/<pane>.
<side>
left, right, top or bottom.
--position <number>
Where in that side, counting the panels already there from the left, starting at 0. The end of the side when it is not given.
--fill
Make that side run the whole length of its edge, the way letting go on the band's Fill whole side target does. See panel fill.
unluminous-cli panel dock terminal right
unluminous-cli panel dock terminal left --position 0
unluminous-cli panel dock agent-chat/chat right --fill

panel fill

unluminous-cli panel fill <left|right|top|bottom> [on|off]

Make a side of the window run the whole length of its edge, or stop it. Each corner of the window belongs to one of the two sides that meet there, and by default the top and the bottom own all four, so a strip along the bottom runs under a column on the right. A side that fills owns both of its corners: a column that fills is as tall as the window and the strips stop at its edge, and a strip that fills takes its corners back. This is the panel menu's Fill Whole row. Left out, on is meant; panel list says which sides fill.

<side>
left, right, top or bottom.
[state]
on or off. On when it is left out.
unluminous-cli panel fill right
unluminous-cli panel fill bottom
unluminous-cli panel fill right off

panel size

unluminous-cli panel size <panel> [--width <points>] [--height <points>]

Set how wide or how tall a panel is, including a pane a plugin contributed. A panel at the left or the right is read by its width and one along the top or the bottom by its height, so both are kept and moving a panel does not lose the size it had on the other side. The same numbers are settings set panes.<panel>.width and .height.

<panel>
explorer, terminal, run, debug, or a contributed pane's <plugin>/<pane>.
--width <points>
How wide it is when it is a column at the left or the right.
--height <points>
How tall it is when it is in a strip along the top or the bottom.
unluminous-cli panel size debug --width 640
unluminous-cli panel size terminal --height 320
unluminous-cli panel size agent-chat/chat --width 1150

panel zoom

unluminous-cli panel zoom <panel> [factor]

Make everything in a panel bigger or smaller, which is what Ctrl/Cmd and the wheel over it does. The explorer and a pane a plugin contributed carry a multiplier of their own; the terminal, run and debug tiles are character grids and their zoom is the terminal's font size, so a zoom there walks settings set terminal.font.size and both say the same number.

<panel>
explorer, terminal, run, debug, or a contributed pane's <plugin>/<pane>.
[factor]
How much bigger than usual, between 0.5 and 3. Left out, it says what the panel is at now; reset puts it back to 1.
unluminous-cli panel zoom explorer 1.35
unluminous-cli panel zoom agent-chat/chat
unluminous-cli panel zoom explorer reset

panel reset

unluminous-cli panel reset

Put every panel back where a new Unluminous has it: the explorer down the left, the three tiles along the bottom, each at its starting size.

unluminous-cli panel reset

window

The window's size and place, its status bar line, and a screenshot of it.

window screenshot

unluminous-cli window screenshot <file> [--timeout <milliseconds>]

Write what the window is showing to a PNG file. The picture is of the real window, so it is how what a command did can be looked at.

<file>
Where to write the PNG. A folder that is not there is made.
--timeout <milliseconds>
How long to wait for the picture. 5000 by default.
unluminous-cli window screenshot _agent_output/after.png

window focus

unluminous-cli window focus

Bring the window to the front and give it the keyboard.

unluminous-cli window focus

window size

unluminous-cli window size [--width <points>] [--height <points>]

Read how large the window is, or set it. A fixed size is what makes two screenshots comparable.

--width <points>
How wide to make it.
--height <points>
How tall to make it.
unluminous-cli window size
unluminous-cli window size --width 1100 --height 720

window position

unluminous-cli window position [--x <points>] [--y <points>]

Read where the window is on the screen, or move it.

--x <points>
How far from the left of the screen.
--y <points>
How far from the top of the screen.
unluminous-cli window position --x 40 --y 40

window message

unluminous-cli window message [text]

Read the line the status bar is showing, or put a line of your own there.

[text]
What to show. The line is cleared when this is left out.
unluminous-cli window message
unluminous-cli window message Ready for the next step

browser

Browser tabs: open an address or a local page, its history, reload and zoom.

browser open

unluminous-cli browser open <address> [--system]

Render an HTTP address or local HTML file in a new Unluminous tab, or with --system open an HTTP address in the person's default browser outside Unluminous, which is what Open in Default Browser on a link's right click menu does.

<address>
An HTTP or HTTPS address, or an HTML path relative to the project folder.
--system
Open the address in the default browser of the operating system instead. Only http and https addresses.
unluminous-cli browser open https://example.com
unluminous-cli browser open examples/site/index.html
unluminous-cli browser open --system https://example.com

browser status

unluminous-cli browser status

Read the address, title, loading state, whether this is the tab the one view is pointed at, and the history directions of the rendered tab that is showing.

unluminous-cli browser status --json

browser history

unluminous-cli browser history [text]

List the addresses visited in Unluminous's browser tabs and nodes, in every project, the most visited first. The list is kept in the settings folder, so it survives a restart and an upgrade, and it is what the address fields offer while an address is typed. With words given, only the addresses whose address or title holds every one of them.

[text]
Words to look for in the address or the title.
unluminous-cli browser history
unluminous-cli browser history github egui --json

browser back

unluminous-cli browser back

Go back through the rendered tab's own history, which is kept apart from every other tab's.

unluminous-cli browser back

browser forward

unluminous-cli browser forward

Go forward through the rendered tab's own history.

unluminous-cli browser forward

browser reload

unluminous-cli browser reload

Reload the rendered tab that is showing, including its linked local resources.

unluminous-cli browser reload

browser zoom

unluminous-cli browser zoom [factor]

Zoom the page of the rendered tab that is showing, as Ctrl or Cmd with the wheel does. With nothing it says the zoom.

[factor]
0.25 to 5, in, out or reset.
unluminous-cli browser zoom 1.5

highlight

Coloured marks behind passages, in one file or across the project.

highlight list

unluminous-cli highlight list [path] [--all]

What is marked, in one file or across the whole project: where each passage is, what color it is in, and the text under it.

[path]
The file to list. The tab that is showing when it is left out.
--all
List every file in the project rather than one.
unluminous-cli highlight list --json
unluminous-cli highlight list --all --json

highlight add

unluminous-cli highlight add [path] [--from-line <number>] [--from-column <number>] [--to-line <number>] [--to-column <number>] [--text <words>] [--color <name>]

Mark a passage in a colour. Give it lines and columns, or --text to mark every occurrence of some words. The file need not be open.

[path]
The file to mark. The tab that is showing when it is left out.
--from-line <number>
The line the passage starts on, counting from 1.
--from-column <number>
The column it starts at. 1 when it is left out.
--to-line <number>
The line it ends on. The line it started on when it is left out.
--to-column <number>
The column it ends at. The end of the line when it is left out.
--text <words>
Mark every occurrence of these words in the file instead of a range.
--color <name>
yellow, green, blue, pink, or a color of your own as #rrggbb or #rrggbbaa. Yellow when it is left out.
unluminous-cli highlight add --from-line 12 --to-line 18
unluminous-cli highlight add src/main.rs --from-line 40 --to-line 44 --color blue
unluminous-cli highlight add src/main.rs --text "unwrap()" --color pink

highlight clear

unluminous-cli highlight clear [path] [--from-line <number>] [--to-line <number>] [--all]

Take marks away: a range of lines, a whole file, or every file in the project.

[path]
The file to clear. The tab that is showing when it is left out.
--from-line <number>
The first line to clear, counting from 1. The whole file when it is left out.
--to-line <number>
The last line to clear. The line it started on when it is left out.
--all
Clear every file in the project.
unluminous-cli highlight clear
unluminous-cli highlight clear src/main.rs --from-line 40 --to-line 44
unluminous-cli highlight clear --all

highlight apply

unluminous-cli highlight apply [--from-file <path>] [--json-text <json>] [--replace]

Mark many passages across many files in one go, from a JSON array of {path, fromLine, toLine, fromColumn, toColumn, color} objects.

--from-file <path>
Read the JSON array from this file.
--json-text <json>
The JSON array itself, for a short list. Quote it.
--replace
Clear every mark in the project first, so what is applied is all there is.
unluminous-cli highlight apply --from-file marks.json
unluminous-cli highlight apply --json-text '[{"path":"src/main.rs","fromLine":1,"toLine":3}]'

fold

Folding blocks in the tab that is showing.

fold list

unluminous-cli fold list

Every block in the tab that is showing that can be collapsed: which line it starts on, which line it ends on, how many lines it hides, what kind of block it is, and whether it is collapsed now.

unluminous-cli fold list --json

fold toggle

unluminous-cli fold toggle [--line <number>] [--regions]

Collapse a block that is showing, or expand one that is collapsed. The block at the caret when no line is given. The answer is how many blocks are collapsed; --regions adds the list.

--line <number>
The line the block starts on, counting from 1. fold list says which lines those are.
--regions
Also answer with the list of every block and whether it is collapsed.
unluminous-cli fold toggle
unluminous-cli fold toggle --line 42
unluminous-cli fold toggle --regions --json

fold collapse

unluminous-cli fold collapse [--line <number>] [--all] [--recursive] [--regions]

Collapse one block, every block in the file, or one block and every block inside it. The answer is how many blocks are collapsed; --regions adds the list.

--line <number>
The line the block starts on, counting from 1.
--all
Collapse every block in the file.
--recursive
With --line, collapse that block and every block inside it rather than just that block.
--regions
Also answer with the list of every block and whether it is collapsed.
unluminous-cli fold collapse --all
unluminous-cli fold collapse --line 42
unluminous-cli fold collapse --line 42 --recursive
unluminous-cli fold collapse --all --regions --json

fold expand

unluminous-cli fold expand [--line <number>] [--all] [--recursive] [--regions]

Expand one block, show all again, or expand one block and every block inside it. The answer is how many blocks are collapsed; --regions adds the list.

--line <number>
The line the block starts on, counting from 1.
--all
Expand every block in the file.
--recursive
With --line, expand that block and every block inside it, opening the whole of it rather than one level.
--regions
Also answer with the list of every block and whether it is collapsed.
unluminous-cli fold expand --all
unluminous-cli fold expand --line 42
unluminous-cli fold expand --line 42 --recursive
unluminous-cli fold expand --all --regions --json

fold others

unluminous-cli fold others [--selection] [--regions]

Collapse everything that does not hold a marked passage, so only the marked parts of the file are left showing. Falls back to the selection when nothing is marked. The answer is how many blocks are collapsed; --regions adds the list.

--selection
Keep what is selected rather than what is marked, even when there are marks.
--regions
Also answer with the list of every block and whether it is collapsed.
unluminous-cli fold others
unluminous-cli fold others --selection
unluminous-cli fold others --regions --json

settings

Every setting: list, read, change and reset them.

settings list

unluminous-cli settings list

Every setting, with its value, what it means and what it will accept. The names are the ones in Unluminous's own settings file.

unluminous-cli settings list --json

settings get

unluminous-cli settings get <key>

Read one setting.

<key>
The name, such as appearance.font.size.
unluminous-cli settings get appearance.font.size

settings set

unluminous-cli settings set <key> <value>

Change one setting. It takes effect at once, in every tab, and is written to the settings file.

<key>
The name, such as appearance.background.opacity.
<value>
The new value.
unluminous-cli settings set appearance.font.size 20
unluminous-cli settings set appearance.background.opacity 0.5
unluminous-cli settings set editor.line_numbers false
unluminous-cli settings set terminal.shell cmd.exe
unluminous-cli settings set appearance.font.family "Courier New"

settings reset

unluminous-cli settings reset [key]

Put a setting, or every setting, back to what an Unluminous that has never been run has.

[key]
The setting. All of them when it is left out.
unluminous-cli settings reset appearance.font.size
unluminous-cli settings reset

settings telemetry

unluminous-cli settings telemetry [--flush]

Whether this window sends anonymous usage statistics, why not when it does not, and what it has sent: the client id, the requests posted and failed, and how many counted names are waiting. Turn it off with settings set telemetry.enabled false.

--flush
Send what is waiting now rather than at the next request, about every twenty minutes.
unluminous-cli settings telemetry --json
unluminous-cli settings telemetry --flush

settings keymap

unluminous-cli settings keymap [filter] [--changed]

Every action a keyboard shortcut can be given: its name, its menu, the shortcut it is on now, and where that came from (unluminous, preset, yours or fixed). Choose a preset with settings set keymap.preset intellij (or vscode, unluminous); change one shortcut with settings bind.

[filter]
Only the actions whose name, menu or shortcut contains this, such as duplicate or ctrl+d.
--changed
Only the actions whose shortcut is not Unluminous's own.
unluminous-cli settings keymap
unluminous-cli settings keymap ctrl+d
unluminous-cli settings keymap --changed --json

settings bind

unluminous-cli settings bind [action] [chord] [--reset] [--reset-all]

Give an action a keyboard shortcut, as Settings -> Keymap does when a key is pressed on its row. A shortcut another action has is taken from it, and the answer says which. none takes the action's shortcut away. Shortcuts that typing and the clipboard read, such as Ctrl+C or a bare letter, are refused.

[action]
The action, as settings keymap names it, such as duplicate-line.
[chord]
The shortcut, such as Ctrl+Shift+D, Alt+F7 or F12, or none.
--reset
Take your own shortcut for this action away, so it is on the preset's again.
--reset-all
Take every one of your own shortcuts away.
unluminous-cli settings bind duplicate-line Ctrl+Shift+D
unluminous-cli settings bind git-show-diff none
unluminous-cli settings bind duplicate-line --reset
unluminous-cli settings bind --reset-all

settings acp-registry

unluminous-cli settings acp-registry [filter] [--refresh] [--timeout <milliseconds>]

The agents in the ACP registry (agentclientprotocol.com), which speak the Agent Client Protocol: each one's id, version, name, how it is distributed (npx, uvx or binary), whether it runs on this machine and whether it is already an endpoint. Read once a window and kept; --refresh reads it again. Add one with settings acp-add.

[filter]
Only the agents whose id or name contains this, such as claude or gemini.
--refresh
Read the registry again rather than using the copy this window already read.
--timeout <milliseconds>
How long to wait for the registry. 12000 by default.
unluminous-cli settings acp-registry
unluminous-cli settings acp-registry claude --json
unluminous-cli settings acp-registry --refresh

settings acp-add

unluminous-cli settings acp-add <id> [--name <endpoint>] [--timeout <milliseconds>]

Add an agent from the ACP registry as an acp endpoint, which Agent Chat can then use. An npx or uvx agent runs through that package runner; a binary agent is downloaded into the settings folder, its SHA-256 checked, and unpacked first. Answers the endpoint's name; plugins run agent-chat use <name> chooses it. Change it afterwards with settings set ai.provider.<n>.args.

<id>
The agent's id, as settings acp-registry lists it, such as claude-acp.
--name <endpoint>
What to call the endpoint. The agent's id by default.
--timeout <milliseconds>
How long to wait, including a download. 600000 by default.
unluminous-cli settings acp-add claude-acp
unluminous-cli settings acp-add gemini --name gemini-acp --json

settings acp-update

unluminous-cli settings acp-update <id> [--timeout <milliseconds>]

Bring an agent added from the ACP registry up to the version the registry has now. An npx or uvx agent's endpoint is changed at once; a binary agent is downloaded and checked first. The endpoint keeps its name and its model. settings acp-registry says which agents are out of date.

<id>
The agent's id, which is the endpoint's name, such as claude-acp.
--timeout <milliseconds>
How long to wait, including a download. 600000 by default.
unluminous-cli settings acp-update claude-acp

settings acp-remove

unluminous-cli settings acp-remove <id>

Take away an agent added from the ACP registry: its endpoint, and the files downloaded for a binary agent. The last endpoint cannot be removed.

<id>
The agent's id, which is the endpoint's name, such as claude-acp.
unluminous-cli settings acp-remove claude-acp

settings fonts

unluminous-cli settings fonts [--limit <number>]

The font families this machine has that the editor can be set to.

--limit <number>
At most this many. 100 by default.
unluminous-cli settings fonts --json

theme

The themes: list them, read one, and paint the window in one.

theme list

unluminous-cli theme list

Every theme that can be chosen, with the plugin it came from and the six colors it is most recognizable by, and which one the window is painted in now.

unluminous-cli theme list --json

theme show

unluminous-cli theme show [theme]

One theme in full: every color in Unluminous's palette by name, the nine token colors, and which drawn icon set it uses. The one the window is painted in when no theme is named.

[theme]
Its key, themes-bundle-1/dracula, or its name, Monokai Pro. The active one when it is left out.
unluminous-cli theme show --json
unluminous-cli theme show "Monokai Pro" --json

theme set

unluminous-cli theme set <theme> [--accent <color>] [--icons <set>]

Paint the window in a theme. It takes effect at once, in every tab and every pane, and is written to the settings file.

<theme>
Its key, themes-bundle-1/dracula, or its name, Material Deep Ocean.
--accent <color>
One color for everything the accent means, as #RRGGBB. none puts it back to the theme's own.
--icons <set>
Which drawn icon set to use: material, classic, or follow for whichever the theme names.
unluminous-cli theme set "Unluminous Light"
unluminous-cli theme set themes-bundle-1/dracula
unluminous-cli theme set "Monokai Pro" --icons material
unluminous-cli theme set unluminous/dark --accent none

background

The pictures behind the window.

background list

unluminous-cli background list

The pictures Unluminous is keeping, and which one is behind the window now. An empty name is the desktop showing through, which is what an Unluminous that has never chosen one does.

unluminous-cli background list --json

background add

unluminous-cli background add <file> [--keep]

Copy a picture into Unluminous's backgrounds folder and draw the window on it. PNG, JPEG, WebP, BMP, GIF or TIFF. The copy is named after the file it came from, with a number added when that name is taken, so adding the same picture twice keeps both.

<file>
The picture to copy in, relative to the project or absolute.
--keep
Copy it in without drawing the window on it.
unluminous-cli background add ~/Pictures/nebula.jpg
unluminous-cli background add wallpapers/dark.png --keep

background use

unluminous-cli background use [name]

Draw the window on one of the pictures Unluminous is keeping, by the name background list prints. No name at all puts it back to the desktop showing through.

[name]
The picture's file name. Left out, the desktop shows through again.
unluminous-cli background use nebula.jpg
unluminous-cli background use

background remove

unluminous-cli background remove <name>

Delete one of the pictures Unluminous is keeping. Only a name is taken, never a path, so nothing outside that folder can be reached. Removing the one that is showing puts the window back to the desktop.

<name>
The picture's file name, as background list prints it.
unluminous-cli background remove nebula.jpg

project

Open another folder in this window, and the recent projects.

project open

unluminous-cli project open <folder>

Show another folder in this window. What was open in the project being left is written down first.

<folder>
The folder to show.
unluminous-cli project open C:\jason\dev\unluminous

project recent

unluminous-cli project recent

The projects that have been open, newest first.

unluminous-cli project recent --json

update

Check for a newer Unluminous, install it, or skip a version.

update check

unluminous-cli update check [--timeout <milliseconds>]

Whether a newer Unluminous has been released. One request to unluminous.com, then the public GitHub releases if the site does not answer. Reports; update install installs.

--timeout <milliseconds>
How long to wait for the answer. 15000 by default.
unluminous-cli update check --json

update install

unluminous-cli update install [--no-restart]

Install & Restart: download the newer version the last check found, check its size and SHA-256, install it, and reopen. Answers at once; update status says how far it got.

--no-restart
Download and check it, and install nothing.
unluminous-cli update install
unluminous-cli update install --no-restart --json

update skip

unluminous-cli update skip [version]

Don't Ask Again: the daily check stops offering this version. A later one is offered.

[version]
The version. The one the last check found when left out.
unluminous-cli update skip 0.55.0

update status

unluminous-cli update status

The last check's answer, an install's progress, the declined version, and the offer showing with its buttons.

unluminous-cli update status --json

mcp

The MCP server agents use: install it into an agent, serve it, and see the tools it offers.

mcp serve

unluminous-cli mcp serve [--transport <stdio|http>] [--port <number>] [--tools <grouped|every>] [--areas <list>] [--instance <which>]

Run the Model Context Protocol server, which is how an AI agent drives Unluminous. Over stdin and stdout by default, which is what an agent that launches it wants; over HTTP with --transport http.

--transport <stdio|http>
How the client talks to it. stdio by default.
--port <number>
Which port to listen on, for --transport http. 7345 by default.
--tools <grouped|every>
One tool per area, or one tool per command. grouped by default.
--areas <list>
Offer only these areas' tools, separated by commas, such as search. All of them by default.
--instance <which>
Which running Unluminous to drive, when several are running.
unluminous-cli mcp serve
unluminous-cli mcp serve --transport http --port 7345
unluminous-cli mcp serve --areas search

mcp status

unluminous-cli mcp status

What this Unluminous is doing about MCP: whether it is serving over HTTP, on which port, in which tool shape, how many tools that is, and where an agent's configuration should point.

unluminous-cli mcp status --json

mcp install

unluminous-cli mcp install <claude|codex|opencode|pi|both|all> [--transport <stdio|http>] [--port <number>] [--scope <user|project>] [--name <name>] [--remove]

Write Unluminous's MCP server into an agent's own configuration, so it is there next time the agent starts.

<client>
claude, codex, opencode, pi, both (Claude Code and Codex) or all.
--transport <stdio|http>
Which way the agent should talk to it. stdio by default, which needs no port.
--port <number>
The port to point at, for --transport http.
--scope <user|project>
user for every project, project for this folder only. user by default.
--name <name>
What the server is called in the agent's configuration. unluminous by default.
--remove
Take it out again rather than putting it in.
unluminous-cli mcp install all
unluminous-cli mcp install opencode
unluminous-cli mcp install claude --scope project

mcp config

unluminous-cli mcp config [claude|codex|opencode|pi] [--transport <stdio|http>] [--port <number>] [--name <name>]

Print the configuration to paste into an agent that has no button of its own: the JSON an mcpServers block wants, the TOML Codex wants, the mcp entry OpenCode wants, and the mcpServers block Pi wants.

[client]
claude, codex, opencode or pi. All of them when it is left out.
--transport <stdio|http>
Which way to describe. stdio by default.
--port <number>
The port to name, for --transport http.
--name <name>
What to call the server. unluminous by default.
unluminous-cli mcp config
unluminous-cli mcp config codex --transport http

mcp tools

unluminous-cli mcp tools [--tools <grouped|every>] [--areas <list>] [--count]

The tools the MCP server offers, exactly as it would answer tools/list. This is how to see what an agent will be given, and how the cost of the two shapes is compared. With --areas it says what equipping an agent with only some of the catalog would cost, which is the number mcp serve --areas is chosen against.

--tools <grouped|every>
Which shape to print. grouped by default.
--areas <list>
Only the areas named, separated by commas. All of them when it is left out.
--count
Print how many tools and how large the list is, rather than the list.
unluminous-cli mcp tools --json
unluminous-cli mcp tools --tools every --count
unluminous-cli mcp tools --count --areas editor,git

input

Mouse and keyboard events for gestures no other command names, such as a drag or a right click.

input move

unluminous-cli input move <x> <y>

Move the pointer to a place in the window and leave it there, which is what makes something hover. Positions are the window's own points with 0,0 at its top left corner - the same points window screenshot writes out, so a position measured off a picture is the position to use. Nothing about this needs the window to be in front: the person's own pointer does not move and the window is never activated.

<x>
Across the window, in points.
<y>
Down the window, in points.
unluminous-cli input move 300 220

input click

unluminous-cli input click <x> <y> [--right] [--middle] [--twice] [--ctrl] [--shift] [--alt] [--cmd]

Click at a place in the window: the pointer moves there, the button goes down and comes up again, over three frames, which is what makes it a click rather than a flicker. The window does not have to be in front and is not brought to the front. Positions are the window's own points, which is what window screenshot writes out.

<x>
Across the window, in points.
<y>
Down the window, in points.
--right
The secondary button, which opens a context menu.
--middle
The middle button, which closes a tab.
--twice
Two clicks, which is a double click.
--ctrl
Hold control.
--shift
Hold shift.
--alt
Hold alt.
--cmd
Hold command on macOS, control on Windows - the key a menu shortcut names.
unluminous-cli input click 300 220
unluminous-cli input click 120 96 --twice
unluminous-cli input click 300 220 --right

input drag

unluminous-cli input drag <x> <y> [--to-x <points>] [--to-y <points>] [--steps <count>]

Drag from one place in the window to another: the pointer arrives, the button goes down, it is moved in steps, and it is let go. The steps are frames of their own because that is what a drag is - every drag in Unluminous is settled from the difference between two frames.

<x>
Where the drag starts, across the window.
<y>
Where the drag starts, down the window.
--to-x <points>
Where it ends, across the window.
--to-y <points>
Where it ends, down the window.
--steps <count>
How many positions it is moved through. 20 when it is not given.
unluminous-cli input drag 660 110 --to-x 1250 --to-y 700

input key

unluminous-cli input key <key> [--ctrl] [--shift] [--alt] [--cmd] [--times <count>]

Press a key and let it go, in whatever has the keyboard. The name is the one egui uses: a letter, a digit, Enter, Escape, Tab, Backspace, Delete, Space, ArrowUp, F2 and the rest. A key produces no text - input text is what types.

<key>
The key's name.
--ctrl
Hold control.
--shift
Hold shift.
--alt
Hold alt.
--cmd
Hold command on macOS, control on Windows - the key a menu shortcut names.
--times <count>
Press it more than once, up to 200.
unluminous-cli input key Escape
unluminous-cli input key ArrowDown --times 3
unluminous-cli input key s --cmd

input text

unluminous-cli input text <text>

Type into whatever has the keyboard, one character a frame. Each character is sent as the key press and the text a real keyboard produces, because the editing area reads one and a text box reads both.

<text>
What to type. It is the rest of the line, so it needs no quoting.
unluminous-cli input text hello there

input wheel

unluminous-cli input wheel <notches> [--across <notches>] [--ctrl] [--cmd]

Turn the mouse wheel where the pointer is, in notches. A negative number scrolls down the page, which is what turning the wheel towards you does. input move is what puts the pointer over the thing to scroll.

<notches>
How many notches, negative for down the page.
--across <notches>
Sideways, for a list that scrolls that way.
--ctrl
Hold control, which is what zooms.
--cmd
Hold command, which is what zooms on macOS.
unluminous-cli input wheel -3
unluminous-cli input wheel 2 --ctrl

report

report open

unluminous-cli report open [--kind <bug|feature|question>] [--title <text>] [--description <text>]

Open the Report an Issue modal, photographing the window and filling in what is named.

--kind <bug|feature|question>
A bug when left out.
--title <text>
One line.
--description <text>
What happened.
unluminous-cli report open --title "Ctrl+D does nothing in a terminal"

report status

unluminous-cli report status

The draft as data, and the issue address once it is sent.

unluminous-cli report status --json

report set

unluminous-cli report set [--kind <bug|feature|question>] [--title <text>] [--description <text>] [--logs <on|off>] [--system <on|off>]

Change the draft.

--kind <bug|feature|question>
The kind.
--title <text>
One line.
--description <text>
What happened.
--logs <on|off>
Include the crash log.
--system <on|off>
Include the version and system.
unluminous-cli report set --kind feature --logs off

report attach

unluminous-cli report attach <path>

Attach a file.

<path>
The file to attach.
unluminous-cli report attach notes/repro.txt

report detach

unluminous-cli report detach <name>

Take an attachment off by its name.

<name>
Such as window.png.
unluminous-cli report detach window.png

report screenshot

unluminous-cli report screenshot

Photograph the window without the modal and attach it.

unluminous-cli report screenshot

report send

unluminous-cli report send [--no-browser]

Open the issue, already written, in the browser, with the attachments on the clipboard. Needs a title.

--no-browser
Answer the address and open nothing.
unluminous-cli report send --json
unluminous-cli report send --no-browser --json

report close

unluminous-cli report close [--discard]

Close the modal, keeping the draft.

--discard
Throw the draft away.
unluminous-cli report close
unluminous-cli report close --discard

setup

setup status

unluminous-cli setup status

Each setup step's state, and whether the dialog is open.

unluminous-cli setup status --json

setup open

unluminous-cli setup open

Open the Set Up Unluminous dialog.

unluminous-cli setup open

setup run

unluminous-cli setup run [steps]

Press Run Setup: take the steps named, or every one not done. Answers at once.

[steps]
path, claude, codex, opencode, pi, speech-model, microphone, comma separated.
unluminous-cli setup run claude,codex

setup decline

unluminous-cli setup decline <steps>

Say no to steps, so they are not offered again.

<steps>
As for setup run.
unluminous-cli setup decline microphone

setup project

unluminous-cli setup project [folder]

In a window started with no project, choose the folder it opens once setup has run. With no folder, says whether the window is waiting for one.

[folder]
The folder to open, as an absolute path.
unluminous-cli setup project C:\jason\dev\notes

setup close

unluminous-cli setup close [--dont-show-again]

Close the dialog; a run carries on.

--dont-show-again
Stop it opening by itself.
unluminous-cli setup close

voice

voice status

unluminous-cli voice status

Engine, model, microphone access, listening, and the dictation's words so far.

unluminous-cli voice status --json

voice dictate

unluminous-cli voice dictate [on|off] [--from <node>] [--into <where>] [--send]

The microphone button: words fill a prompt as they are spoken.

[state]
on, off, or nothing to toggle
--from <node>
A chat node's prompt.
--into <where>
description: the open ticket's.
--send
With off: send when done.
unluminous-cli voice dictate on

voice listen

unluminous-cli voice listen [on|off]

Always listen for "Sable", then dictate into the side pane. The voice.always_listen setting.

[state]
on, off, or nothing to toggle
unluminous-cli voice listen on

voice transcribe

unluminous-cli voice transcribe <path> [--live] [--timeout <milliseconds>]

Transcribe a WAV file with the chosen engine and answer the text. --live plays it in real time into the prompt.

<path>
A WAV file.
--live
Fill the prompt as it plays.
--timeout <milliseconds>
120000 by default.
unluminous-cli voice transcribe clip.wav

voice hear

unluminous-cli voice hear <path> [--live]

Hear a WAV file as if from the microphone: through the wake word when listening, else into the dictation.

<path>
A WAV file.
--live
At the speed it was spoken.
unluminous-cli voice hear clip.wav

voice install

unluminous-cli voice install

Download the local speech model (66 MB) and ONNX Runtime, for a build no installer made. An installed Unluminous already carries both, and this says so.

unluminous-cli voice install

voice microphone

unluminous-cli voice microphone [ask|open-settings]

Microphone access; ask asks the system, open-settings opens its privacy page.

[action]
ask or open-settings
unluminous-cli voice microphone