Updated September 27, 2026

Agents and remote control

Use the semantic remote API to inspect and control a running Gloomberb desktop or TUI session.

What this is

The remote API drives a running Gloomberb app. Agents and scripts read semantic state, open panes, navigate tickers, arrange layouts, and call plugin capabilities, with no screen coordinates.

Use it to operate the live desktop or TUI. Use the CLI for headless data, reports, and screenshots. Use the hosted MCP server when you only need Cloud data and no terminal is running.

Launch the app first. Pass --app desktop or --app tui when both may be running. No endpoint found? Check the session is still open and rerun remote help.

Core concepts

Concept	Meaning
App kind	`desktop` and `tui` are separate surfaces. `--app` picks one.
Resources	Read-only state: `app://snapshot`, `app://panes`, `app://pane-templates`, `app://commands`, `app://capabilities`, `ui://tree`.
Operations	Mutations: `app.search`, `commandBar.activateResult`, `pane.createFromTemplate`, `pane.focus`, `ticker.navigate`, `layout.setGrid`, `ui.invokeMatching`.
Capabilities	Plugin service operations. Use app operations for UI, capabilities for plugin-owned data and side effects.

Every operation changes only the local app, except capability.invoke, which runs a plugin capability and can reach external services. Nothing asks for confirmation.

CLI quick reference

Command	Use
`gloomberb remote help`	Agent-focused usage from the running app.
`gloomberb remote schema`	Resource URIs, operations, request and response shapes.
`gloomberb remote get <resource>`	Read one resource.
`gloomberb remote call <operation> [json] [--dry-run]`	Invoke one operation.
`gloomberb remote patch <resource> <json-patch> [--expect-rev rev] [--dry-run]`	JSON Patch a mutable resource.
`gloomberb remote batch <json> [--dry-run]`	Run a multi-step workflow.
`gloomberb remote watch <resource> [--interval ms] [--limit n]`	Poll for changes.

All take --app desktop|tui 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.

Read before acting

The snapshot has the config and layout, focused pane, panes, command-bar state, UI tree, and schema. Plugin capabilities are in app://capabilities.

bash

gloomberb remote get app://snapshot --app desktop --json
gloomberb remote get app://pane-templates --app desktop --json
gloomberb remote get ui://tree --app desktop --json

Open panes

When you know the pane, use a pane operation.

bash

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

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

bash

gloomberb 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 } }
  ]
}' --app desktop --json

Arrange the workspace

bash

gloomberb remote call layout.setGrid '{ "columns": 2 }' --app desktop --json
gloomberb remote call layout.focusRegion '{ "region": "right" }' --app desktop --json
gloomberb remote call layout.closeFloating '{}' --app desktop --json

Switch panels without touching layout internals:

bash

gloomberb remote call app.switchPanel '{ "panel": "right" }' --app desktop --json

remote patch works on the resources remote schema marks patchable: app://config, app://layout/current, app://pane-state/{paneId}, 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.

bash

gloomberb remote get ui://tree --app desktop --json
gloomberb remote call ui.invokeMatching '{ "role": "button", "label": "Done", "action": "press" }' --app desktop --json

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