Building a Workbench

Pair through the CLI, frame the editor, and speak its postMessage protocol.

Applies To

livediagram, liveplanner, livedocuments and livedesign

Your tool never holds a every app credential. It runs the person's own CLI, which holds their token, to get a ticket: a single-use link that opens one file in a frame, signed in as that person. The frame then talks to your tool with window.postMessage.

Your Origin

Everything is bound to your tool's origin, exactly scheme://host[:port] as the browser reports it in event.origin: https on any host, or http only on localhost, 127.0.0.1 or [::1]. No path, query, trailing slash or default port. https://127.0.0.1:5175 is valid; https://127.0.0.1:5175/ and http://192.168.1.4:5175 are refused with invalid_origin.

Pairing is per origin, so the same tool on a laptop and on a LAN address pairs twice.

Pairing

A token opens files only in a workbench its owner has approved. The first time, run:

--name is optional, 1 to 40 characters, and is only a label shown beside the origin. The command prints the approval link on its first line of stdout before it waits (with --json, a line {"status":"pending","pairingUrl":"…","expiresAt":…}), so your tool can read it straight away and show it as one button, "Approve in every app". It opens the browser itself only when stdout is a terminal.

The link opens a page headed Allow this workbench? in the person's own signed-in browser, where only the token's owner can choose Allow or Don't allow. The command then exits:

  • 0 once paired, printing paired <origin> as <name> (or {"status":"paired","origin":…,"name":…} with --json). An origin already paired exits 0 at once.
  • 4 when declined (pairing_declined), when the request expired after ten minutes unanswered (pairing_expired), or when it disappeared, for example because the token was revoked (pairing_gone).

A pairing lasts as long as its token. The person can end it from Settings, under API Tokens, with Unpair.

Opening a File

The file can be a name, an id prefix or a every app link to one of the person's own files (a share link is refused). Add --tab with a tab name or id prefix to open on that tab; without it, the editor opens on the first tab. With --json it prints:

If the token is not paired with your origin, the command exits 4 with the code pairing_required and names the workbench pair command to run. Each token can mint 30 tickets a minute (pairing requests share that allowance), which is plenty for opening files but not for polling.

Opening the Workspace

The Frame

A ticket works once, within one minute. Take the app origin from new URL(url).origin and accept messages only from that origin.

The Handshake

The name (1 to 40 characters) appears in the editor's copy, such as "Reconnect in Acme Editor to keep editing."

Messages

Every message is an object { type, v: 1, ... }. The page sends only to your origin and accepts only messages from its parent window at that origin. A message with an unknown type, a different v, or a field that fails validation is ignored (and logged once per type in the page's console), so check your payloads against this table.

Renewing the Session

The page redeems it and carries on without reloading. A ticket for a different file or origin is refused, and the page keeps asking. Renewal can continue as long as the token lives.

When a Session Ends

  • expired: the session ran out without a renewal. The editor shows "Reconnect in" your name "to keep editing."
  • revoked: the token was revoked or the workbench unpaired. The editor shows the same line.
  • trashed: the file was moved to the Trash.
  • refused: the ticket was for a different file than the d in the address.

An ended page never comes back by itself. To reconnect, mint a new ticket and frame the new URL.

The Selection Reference

The reference field is the text to attach to the message the person sends their agent, so the agent reads exactly what was selected at that moment:

Read-Only Tickets

What a Session Can and Cannot Do

Was this article helpful?

Still need help?

Try Troubleshooting, or tell us what you were trying to do.

Contact us