DiceTermAlpha

Scripting API

Drive DiceTerm from scripts over a token-gated localhost HTTP API, with webhooks for events.

DiceTerm exposes a localhost HTTP API that lets you create panes, send keystrokes, run commands, and receive events from triggers — all from a script, a CI job, or another tool running on the same machine.

The API is off by default. Enable it in Settings → Scripting.

Setup

Once enabled, the API listens on port 7373 on localhost. A 48-character hex Bearer token is generated on first use and written to:

%APPDATA%\DiceTerm\api-token.txt

Every request must include this token in the Authorization header:

Authorization: Bearer <token>

If the header is missing or the token is wrong, the API returns 401 Unauthorized.

Endpoints

Method Path Description
GET /sessions List all open panes: id, name, cwd, workspace
GET /sessions/<id>/output Return the last ~64 KB of scrollback for pane <id>
POST /sessions/<id>/text Send raw text to pane <id> — body: {"text": "..."}
POST /sessions/<id>/run Send a command followed by a newline — body: {"command": "..."}
POST /command Execute a named DiceTerm action — body: {"action": "..."}
POST /window/new Open a new DiceTerm window
GET /webhooks List registered webhooks
POST /webhooks Register a webhook — body: {"url": "http://localhost:..."}
DELETE /webhooks Remove a webhook — body: {"url": "http://localhost:..."}

/command actions

Pass any remappable command ID as the action field — for example split, focus-next, broadcast, or layout. Additional fields depend on the action.

Webhooks

Register a webhook URL and DiceTerm will POST JSON to it when events fire. Webhooks may only target localhost URLs. The maximum number of registered webhooks is 32.

Events

Event Payload fields When it fires
capture event, paneId, line A trigger with the "capture" action matched a line of output
command-end event, paneId, exit, durationMs A shell command finished (requires OSC 133 support — auto-enabled for PowerShell and bash)

curl example

List open panes, then run a command in the first one:

TOKEN=$(cat "$APPDATA/DiceTerm/api-token.txt")
 
# List sessions
curl -s -H "Authorization: Bearer $TOKEN" \
  http://localhost:7373/sessions
 
# Run a command in pane "abc123"
curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command": "npm test"}' \
  http://localhost:7373/sessions/abc123/run

Note: The API is localhost-only by design. There is no option to expose it on the network, and webhooks are likewise restricted to localhost targets. This is intentional — see Privacy & security for the full picture.

← PreviousKeyboard shortcutsNext →Privacy & security