Agents and remote control

gloom remote drives a Gloom app running on this machine, terminal (TUI) or desktop. Scripts and local agents read the screen, open panes, pick tickers and arrange layouts by name.

gloom                                   # one terminal: the app
gloom remote help                       # another: the agent guide
gloom remote get app://snapshot --json  # what is on screen

Leave --app out when one app runs. Pass --app tui or --app desktop when both do.

For headless data, reports and a screenshot of a function with no app open, use the CLI.

Commands

All take --app tui|desktop and --json. --dry-run on call only echoes the payload, with no check of the operation or its fields; on patch it returns the patched result without saving.

When no app answers

With --json the reason is in error.code, with message and details (what to do), and the command exits 1:

An endpoint file left by an app that exited without quitting is removed once its process is gone and its port refuses. An unreachable app's file is kept.

Asked for the desktop app while only the terminal app runs:

{ "ok": false, "error": { "code": "app_not_running", "message": "The Gloom desktop app is not running.", "details": "The terminal app is: pass --app tui, or leave --app out." } }

Anything else that fails, such as an operation the app refuses, is cli_error.

Read the screen

app://snapshot is what is on screen in one read:

It leaves out what an agent reads once or rarely:

app://snapshot/full has all of it inline, the shape the snapshot had before 0.20.5. It is often several times the size: 413 KB against 73 KB with nine panes open.

gloom remote get app://pane-templates --json
gloom remote get ui://tree --json

pane.screenshot returns a pane as a PNG (base64 in image.data, with its pixel size): the focused pane, or paneId from app://panes. Desktop only: the terminal app draws text.

gloom remote call pane.screenshot '{}' --app desktop --json

First-run setup

On a new profile the setup dialog covers the app. app://form (and the snapshot's form) reads "open": true, "kind": "setup", with its step, title, fields by id and buttons:

{ "open": true, "kind": "setup", "step": "PORTFOLIO", "title": "What do you hold?",
  "fields": [{ "id": "ticker", "label": "Ticker", "value": "" }, { "id": "shares" }, { "id": "avgCost" }, { "id": "currency" }],
  "buttons": [{ "label": "Skip" }, { "label": "Continue", "disabled": true, "shortcut": "Enter" }] }

While it is open:

• app.search and app.openCommandBar refuse, and app.closeDialog does not close it.
• A change made behind it still runs, and its answer carries warnings saying the setup dialog covers it.
• Its own controls match first in ui.invokeMatching.

Add a ticker and continue, or skip a step:

gloom remote batch '{ "type": "batch", "requests": [
  { "type": "call", "operation": "ui.invokeMatching", "input": { "role": "form-field", "metadata": { "fieldId": "ticker" }, "action": "setValue", "input": "NVDA" } },
  { "type": "call", "operation": "ui.invokeMatching", "input": { "role": "form-field", "metadata": { "fieldId": "ticker" }, "action": "submit" } },
  { "type": "call", "operation": "ui.invokeMatching", "input": { "role": "form", "action": "submit" } }
] }' --json
gloom remote call ui.invokeMatching '{ "role": "button", "label": "Skip", "action": "press" }' --json

• Submit on the Ticker field adds the position; { "role": "form", "action": "submit" } presses the button Enter would.
• Skip leaves one step unfilled. A new profile has two steps, Portfolio and Desks.
• A step can change after the call answers, so read app://form again before the next call.
• When setup is run again, form.actions includes cancel, which skips all of it.

Open panes

When you know the pane, use a pane operation.

gloom remote call pane.createFromTemplate '{ "templateId": "market-heatmap-pane" }' --json
gloom remote call ticker.pin '{ "symbol": "NVDA", "forceNewPane": true }' --json

For command-bar ranking and aliases, search then activate.

gloom remote batch '{
  "type": "batch",
  "include": ["panes", "commandBar"],
  "requests": [
    { "type": "call", "operation": "app.search", "input": { "mode": "ticker", "query": "NVDA" } },
    { "type": "call", "operation": "commandBar.activateResult", "input": { "index": 0 } }
  ]
}' --json

Arrange the workspace

gloom remote call layout.setGrid '{ "columns": 2 }' --json
gloom remote call layout.focusRegion '{ "region": "right" }' --json
gloom remote call layout.closeFloating '{}' --json
gloom remote call app.switchPanel '{ "panel": "right" }' --json

remote patch works on what remote schema marks patchable: app://config, app://layout/current, app://pane-state/{paneId} and app://pane-settings/{paneId}.

Read the resource and its rev first, then pass --expect-rev, so a stale edit fails instead of overwriting.

Semantic UI fallback

No app-level operation? Target UI nodes by role, label, contained text, metadata, or action.

gloom remote call ui.invokeMatching '{ "role": "button", "label": "Open Help", "action": "press" }' --json

Use it sparingly; higher-level operations survive UI changes.

Concepts

• Every operation changes only the local app, except capability.invoke, which runs a plugin capability and can reach external services.
• watchlist.add and watchlist.remove ask in the app first and answer with what happened. Nothing else asks.