Protocol Verbs

Options, themes and the dock

Options, themes and the dock: part of the Protocol Verbs of TUIOS.

This page is one part of docs/protocol-verbs.md of the tuios repository. The Protocol Verbs page lists every part.

apply-config Added in v0.8.1

Apply config.toml now, including the changes that give panes or linked machines more: [agents.permissions], [hosts] and their link policies. A change to the file applies only what narrows those; the rest waits for this verb or a daemon restart. Only the person may call it: it is refused from inside a pane and over a link.

ParamTypeRequiredDefaultDescription
hoststringApply only this host's entry, or its removal, and nothing else in the file. tuios hosts add sends it.
Result fieldTypeDescription
modestring[agents.permissions] mode now in force.
default_grants[]stringWhat a pane started with no grants of its own holds now.
changes[]stringWhat changed, one sentence each: the default grants, hosts added, removed or dialled another way, and link policies.
still_waitingboolTrue when config.toml still holds a change that waits, which happens when only one host was applied.
{"id":1,"verb":"apply-config"}
{"id":1,"verb":"apply-config","params":{"host":"build"}}

get-option Added in v0.8.0

Read an option. Reports the session's override when one is set, then the value config.toml sets, otherwise the default.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
keystringOption path to read.
Result fieldTypeDescription
keystringThe option that was read.
valuestringThe value in effect.
sourcestringWhere the value came from: "session" for an override set on this session, "config" for a value config.toml or a file it brings in sets, "default" for the built-in. One of session, config or default.
defaultstringThe built-in default, so a caller can tell an override from a default that happens to match.
option_typestringbool, int or string.
{"id":1,"verb":"get-option","params":{"session":"work","key":"appearance.dockbar_position"}}

list-dock-components Added in v0.8.0

List the dock's components: what the bar is made of, what each cell reads, and what each component's command last did.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
Result fieldTypeDescription
components[]stringOne entry per placed component, in draw order, carrying its name, side, source, refresh mode, current text, last exit code, last run time and last error.
{"id":1,"verb":"list-dock-components"}
{"id":1,"verb":"list-dock-components","params":{"session":"work"}}

list-glyphs Added in v0.8.0

List the glyph sets and describe one: the roles it names, and the characters that would actually be drawn if it were selected. A glyph set is the shape half of a rice, the way a theme is the colour half, and like a theme its value is a name from an open set standing for a document kept elsewhere.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
glyphsstringDescribe this set as well as listing. Omit to list only.
Result fieldTypeDescription
sets[]stringEvery set id, built-ins first and then the user's.
roles[]stringEvery role a set can name, which is what to write in a set file.
totalintHow many sets there are.
glyphs_dirstringDirectory user sets are read from; write <id>.json there.
activestringThe set in effect, with active_source saying whether it came from the session, config.toml or the default.
problems[]stringOne line per set file that could not be read and per role dropped for being the wrong width. Present only when there are any.
setobjectPresent when glyphs was given: id, display_name, inherits, ascii, names (the roles the set states) and drawn (the character each role would actually render as, defaults folded in).
{"id":1,"verb":"list-glyphs","params":{}}
{"id":1,"verb":"list-glyphs","params":{"session":"work","glyphs":"heavy"}}

list-hooks Added in v0.8.0

List the hook table and what each hook command last did: how many times it ran, its last exit code, when it last ran and its last error.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
eventstringOnly the hooks on this event. Omit for every event.
Result fieldTypeDescription
hooks[]objectOne row per registered command: event, side, command, runs, last_exit, last_run, last_error and last_ms. Side is session for the hooks the daemon runs and client for the ones an attached client runs.
totalintHow many rows the filter matched.
events[]stringEvery event a hook can be written on. An event outside this list is ignored when the config loads.
client_attachedboolWhether a client answered for its half of the table. False means the client rows are missing because nobody is attached, not that no client hooks exist.
{"id":1,"verb":"list-hooks"}
{"id":1,"verb":"list-hooks","params":{"event":"after-new-window"}}

list-options Added in v0.8.0

List every settable configuration path with its type, default, accepted values and description. Use it to find an option path instead of guessing one.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
sectionstringOnly options in this group, e.g. sidebar or dock. The full set of section names is reported on every call.
prefixstringOnly options whose path starts with this, e.g. "appearance.sidebar.".
Result fieldTypeDescription
options[]objectOne row per option: path, type, section, description, default, and accepted/min/max/unit/deprecated where they apply (unit is what a number counts: ms, s, cells, %). session_value is present only where this session carries an override.
sections[]stringEvery section name, whatever the filter matched.
totalintHow many options the filter matched.
{"id":1,"verb":"list-options"}
{"id":1,"verb":"list-options","params":{"section":"sidebar"}}

list-themes Added in v0.8.0

List the registered themes. Name one to also get its colours as hex and the contrast of each against its own background.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
themestringDescribe this theme as well as listing. Omit to list only.
filterstringOnly ids containing this, case-insensitively, e.g. catppuccin.
Result fieldTypeDescription
themes[]stringMatching theme ids, capped at 100. truncated reports when the cap applied.
totalintHow many themes are registered in all.
matchedintHow many the filter matched, before the cap.
activestringThe theme this session is set to. With no theme set, it is omarchy where Omarchy is installed, because the client follows Omarchy there. Elsewhere it is empty, which means the terminal's own colours.
active_sourcestring"session" for a theme set on this session, "config" for one config.toml sets, "default" for the built-in. One of session, config or default.
themes_dirstringWhere a custom theme file goes. Writing <id>.json here registers it. No restart is needed.
problems[]stringOne line per theme file that could not be read, with the reason. Present only when a file is malformed.
paletteobjectPresent when theme was given: id, display_name, dark, bg, fg, cursor, swatches (each with hex, ratio, floor, passes) and illegible, the names of the swatches that did not clear their floor.
{"id":1,"verb":"list-themes","params":{"filter":"catppuccin"}}
{"id":1,"verb":"list-themes","params":{"session":"work","theme":"catppuccin_mocha"}}

refresh-dock Added in v0.8.0

Re-run a dock component now, whatever its refresh mode says.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
componentstringComponent to re-run, named as in the config file. Omit to re-run every one.
Result fieldTypeDescription
componentstringThe component that was refreshed, or "all".
{"id":1,"verb":"refresh-dock","params":{"component":"agents"}}
{"id":1,"verb":"refresh-dock"}

set-option Added in v0.8.0

Set a configuration option. An attached client applies it live. The path and value are checked against the option registry, so a bad call fails instead of reporting success.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
keystringOption path, e.g. "appearance.sidebar.enabled". Call list-options for the full set.
valuestringNew value, as a string. Booleans take true/false/on/off/1/0/yes/no.
no_saveboolApply the value without saving it. Later saves of other settings leave the key in the config files alone. The value stays until the client exits or the option is set again without no_save.
Result fieldTypeDescription
keystringThe option that was set.
valuestringThe value recorded.
appliedboolWhether an attached client applied it to the live display.
no_saveboolThe no_save the daemon used. A daemon that does not return it saves the value.
reasonstringWhy applied is false, when it is. Present only then.
deprecatedstringWhy this path is deprecated and what replaced it. Present only for a deprecated path.
{"id":1,"verb":"set-option","params":{"session":"work","key":"appearance.sidebar.enabled","value":"true"}}
{"id":1,"verb":"set-option","params":{"session":"work","key":"appearance.dockbar_position","value":"top"}}
{"id":1,"verb":"set-option","params":{"session":"work","key":"appearance.sidebar.enabled","value":"false","no_save":true}}

tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.

On this page