How controls send commands — the outbound half of the standardized connection block. The payload vocabulary ({{value}} and friends) is identical across transports; method picks the wire.
Symbol
bolt.fill
Docs
Docs complete
Fields
25 fields, each with what it does.
Fields
Field
Type
Default
What it does
methodmethod
text
—
How the action travels
Picks the wire the action goes out on: meshsocket, mqtt, http or local (the on-device store).
modemode
text
—
Wait for a reply or not
broadcast sends and moves on; request waits for the reply, which only a route_msg command ever gets (meshsocket only).
eventevent
text
—
The message type sent
Sent as-is as the MeshSocket frame type, so it must be a relay verb such as broadcast_request; the command name goes in the payload instead.
payloadpayload
object
—
The data to send
The body sent with the action, with {{value}} replaced by the control's current value.
sourcesource
text
—
Which connection to use
Sends through the layout's named source (mqtt, http or local) instead of spelling out the address.
topictopic
text
—
Where to publish
The MQTT topic the message is published to.
retainretain
on / off
false(off)
Keep the last message
Publishes with the MQTT retained flag so new subscribers get the last value straight away.
urlurl
text
—
The full web address
The absolute address an http action requests.
pathpath
text
—
The part after the host
The path added to the source's base address for an http action.
httpMethodhttpMethod
text
—
GET, POST and so on
The HTTP verb used; it is POST when there is a payload and GET when there is not.
headersheaders
object
—
Extra request headers
Adds these headers to this action's http request only.
opop
choiceone of 9
—
What to do to the data
Chooses the on-device store operation the action runs: write, change, remove or read rows, or adjust a single saved value.
insertadds a new entry to the collection
updatechanges the fields you name on the entry with this id
upsertupdates the entry if it exists, otherwise adds it
deleteremoves the entry with this id
selectmoves the collection's selection to the entry with this id
setpatches the named fields of a singleton collection's one row
incrementadds the step to a number field of a singleton collection
decrementsubtracts the step from a number field of a singleton collection
toggleflips a true or false field of a singleton collection
collectioncollection
text
—
Which list to change
The on-device collection the operation reads or writes.
idid
text
—
Which entry
The entry the operation acts on; {{selected}} uses the collection's current selection.
setset
object
—
The values to save
The field values written by insert, update, upsert or a singleton set, with {{value}} and the store tokens filled in first.
fieldfield
text
—
Which saved value
The single field of a singleton collection that increment, decrement or toggle changes.
byby
number
1
How much to add or take
The step an increment or decrement applies, 1 when unset; a decrement subtracts it, and whole-number fields only take whole steps.
Confirm firstconfirm
choiceone of 1
—
Ask before sending
Shows the app's own confirmation dialog first; the action goes out only when the user taps the confirm button. It applies to taps, form submits and drags in the app; a widget, Live Activity, Control Center or Siri press cannot draw the dialog, so those never fire it.
dialoga dialog drawn by the app that names this layout and where the action goes; Cancel sends nothing; widgets, the Dynamic Island, Control Center and Siri never fire it, so a tile bound to it is not offered
Dialog titleconfirmTitle
text
—
The dialog's question
The headline of the confirmation dialog; without it the control's label is used.
Dialog messageconfirmMessage
text
—
More detail under the question
A line or two under the headline that says what will happen.
Confirm buttonconfirmLabel
text
—
The word on the confirm button
The text on the button that sends the action, such as Remove or Restart; Confirm when unset.
Destructivedestructive
on / off
false(off)
Mark it as hard to undo
Draws the dialog's confirm button in red, for removals and other changes that cannot be taken back.
Expand groupexpand
text
—
Open a group's expanded view
Expands the group (or, from a control inside a list row, that list's row) with this id, as if its card was tapped. No transport is used, so method can be left out.
Collapse groupcollapse
text
—
Close a group's expanded view
Closes the expanded view when it was opened from the group (or list row) with this id; nothing happens otherwise.
Toggle expandtoggleExpand
text
—
Open or close a group's expanded view
Closes the group's expanded view when it is open, opens it when it is not.
Examples
3 examples, each one a control you can paste into a layout.
Opens the expanded view of the group with this id, with no transport involved.
JSON 1 line
{ "expand": "pkg" }
Edit hint — the Binding view. The fields marked edit: data (method, the address for each method: event, topic, url, collection; payload, with {{value}}) are the ones the edit pose's binding view edits up front as what using the control sends. A payload must be a JSON object; the other keys (mode, headers) stay as written.
Edit hint — Ask first.confirm names edit: ask: the binding view's send card asks what a tap does (Send, or one of the edit: pick-control / axis: group fields here, expand, collapse, toggleExpand, with a group picked from the layout) and whether it asks first: Never, Undo after (the control's own confirm: true pill, offered when the control's doc has it) or Ask before (confirm: "dialog"), with the app's dialog drawn live so confirmTitle, confirmMessage and confirmLabel are typed on it and destructive turns its button red.
The app sends eventverbatim as the MeshSocket frame type, and the relay
only dispatches its own verbs — broadcast_request (fan-out to every other
member of the channel), route_msg (targeted request/reply) and
route_msg_noreply (targeted fire-and-forget). Any other name (set_power,
broadcast, arm, …) is silently dropped: nothing errors, no server handler
ever runs, the control does nothing.
So the command name never goes in event. Put it in payload.msg_type —
the relay re-emits a broadcast_request to the channel as a broadcast frame,
and servers demux on msg_type (carterkit's Hub.on("set_power") and
bind.command("set_power") are the two halves of exactly this shape).
Targeted send, when you hold a live relay-assigned target_id (a name is not
resolved here — use route_msg_noreply with target_name for that):
Fire and forget — the mode for broadcast_request and route_msg_noreply
request
Send + await response — only meaningful with route_msg (the relay routes the target's reply back); on a broadcast_request nothing ever replies, so the tap just waits out the timeout
Need an answer to a broadcast command? Use the round trip instead: fire the
command, and Sync the control to the state broadcast the server sends back.
MQTT publishes and HTTP requests are fire-and-forget; failures surface in the
connection console. Ack'd commands (layout state.acks) are a MeshSocket
contract and don't apply to mqtt/http actions.
A string that is exactly"{{value}}" keeps the value's native type (numbers
stay numbers, bools stay bools). Over MQTT, a string payload publishes as raw
bytes (ON, not "ON"); objects publish as JSON.
{{secret:name}} fills in a credential from the phone's Keychain when the
action is sent, never earlier (Secrets). It works in an HTTP
action's url path/query, headers and payload, an MQTT action's payload,
and a MeshSocket action's payload. Only the text you wrote in the action is
filled in; a {{secret:…}} that arrives inside {{value}} is sent as plain
text. The secret must be allowed at the destination:
an HTTP or MQTT action goes to its host, which must be a declared source's
host or listed in the secret's hosts. An absolute url on any other host
needs "hosts": ["that.host"] in the declaration;
a MeshSocket action goes to every peer in the room, so the secret needs
"mesh": true. Without it the action is not sent and the console logs
secret <name> not allowed for the mesh.
Local store
With method: "local" an action writes the layout's on-device Local Store
instead of sending anything. op is one of insert, update, upsert,
delete or select; collection names the target; id picks the row for
update/upsert/delete/select ("{{selected}}" uses the collection's selection
cursor) and set maps declared fields to values for insert/update/upsert.
payload is not used. Tokens are substituted into set and id first —
{{value}} and the control's own tokens plus {{now}}, {{today}},
{{startOfWeek}}, {{startOfMonth}}, {{startOfYear}} and {{selected}} —
and an exact-token string keeps its native type, so "pages": "{{value}}" from a
Symbol color stores a number. Values are validated against the declared types
(reject, never coerce); a failure is a console line and a red Local pipe, never
an alert. Delete is by id only.
A Form's submit action also gets {{form}} (the whole draft object) and
{{form.<field>}} (one draft field), on any transport: "set": "{{form}}" for a
local insert/update, "payload": "{{form}}" for http or meshsocket.
A collection declared singleton: true holds exactly one row, and four more ops
write it without an id: set patches the named fields, increment /
decrement add or subtract by (default 1) from a number or integer field,
and toggle flips a bool field. Each creates the row from the collection's
defaults on its first write.
These four are what the editor's Action tab writes: its verbs Record time, Add 1,
Subtract 1 and Set to… compile to set with {"field": "{{now}}"}, increment,
decrement (no by) and set with one literal field.
Confirmation and Undo
A control with "confirm": true (the editor's Show confirmation, on the Action
tab; off by default) shows a short pill after each of its local writes lands:
what changed and an Undo button, e.g. Count · 84 [Undo]. The pill stays for
3 seconds; the control's next write replaces it, and a write from a control without
confirm takes it down. Undo is one level:
a singleton op (set / increment / decrement / toggle) puts the touched
fields back to their prior values (a first write goes back to the default, else
null) through an ordinary set;
an insert removes the new entry, a delete brings the entry back from Recently
deleted, and an update / upsert restores the row exactly.
A Form's submit follows the submitting button's confirm. Without confirm a
write is silent. The entry sheet and the data browser always offer Undo for their
own adds, edits and deletes.
"confirm": "dialog" on an action asks first: the app draws its own confirmation
dialog over the whole screen and sends the action only when the user taps the
confirm button. Cancel, or 60 seconds without an answer, sends nothing, and a
Knob shadow the tap already flipped goes back. It works on any action and any
transport (a Long Press action, a row or chart tap, a local write). The dialog is
app chrome, not layout styling: it names the layout and where the action goes
(Workshop over Layout · Connect+ · lights), with confirmTitle (default the
control's label), confirmMessage, confirmLabel (default Confirm) and
destructive: true for a red confirm button.
"action": {
"method": "meshsocket", "mode": "broadcast", "event": "broadcast_request",
"payload": { "msg_type": "item.remove", "id": "{{value}}" },
"confirm": "dialog", "confirmTitle": "Remove this item?",
"confirmMessage": "It is removed from the hub.", "confirmLabel": "Remove",
"destructive": true
}
This is a different option from the control's "confirm": true (the Undo pill
above): the pill reports a local write after it lands, the dialog stops an action
before it is sent. Shortcuts, widgets and Control Center do not offer an action that
asks first: it fires only in the app.
Expand and collapse
{"expand": "<group id>"}, {"collapse": "<group id>"} and {"toggleExpand": "<group id>"} act
on the app's expanded view instead of a transport (leave method out). Any control can carry
one: a "More" button with "action": {"expand": "pkg"} opens group pkg from anywhere in the
layout. A control inside a list row names the list's id ({"expand": "packages"}) and opens its
own row. They are the same path as the group's own tap, an expand.trigger control and the hub's
sheet frame (Expand). An id that matches nothing on screen does nothing.
Hub prompts
A layout's hub can ask the user to confirm something (before it installs, removes or
deletes anything) with the routed prompt verb on the layout's socket. The app draws
the same frame, naming the hub and its connection (Example hub over
Hub · Connect+ · lights), one prompt at a time, and answers with a
broadcast_request the hub receives like any action:
choice is confirm, cancel, timeout or busy. Only the layout on screen's own
connection may ask (and, when the layout names a state.authority, only a frame whose
from is that authority); at most 3 wait behind the one shown and 5 are taken per 30
seconds, the rest answer busy. The full wire contract is in docs/HUB-PROMPT.md.