CLI and scripting

Connector accepts the same JSON operation objects through its CLI, app command mode, MCP and AppleScript. Use a script for a repeatable workflow that discovers IDs, makes edits and checks their results.

Connector 0.1.6 automation uses the same trial or paid app license. Start or activate it in Connector’s License section first.

Discover and pin a connection

'/Applications/Connector.app/Contents/MacOS/connector' hosts
'/Applications/Connector.app/Contents/MacOS/connector' catalog

hosts returns running connections, including pid and session. catalog is local documentation. To inspect an individual request contract:

'/Applications/Connector.app/Contents/MacOS/connector' catalog element.setAttribute

Use the actual PID and session from discovery for every subsequent call. Put selectors before the command:

'/Applications/Connector.app/Contents/MacOS/connector' \
  --pid 12345 --session 'SESSION-FROM-DISCOVERY' \
  capabilities

The values above are placeholders. capabilities describes the plugin loaded by that Hype process. Its supported operations can differ from the installed app's catalog until Hype restarts. A pinned session prevents a workflow from silently continuing on a restarted editor.

Request and response format

Pass one JSON object directly, through a file or through standard input:

'/Applications/Connector.app/Contents/MacOS/connector' \
  --pid 12345 --session 'SESSION-FROM-DISCOVERY' \
  run '{"op":"document.list"}'

'/Applications/Connector.app/Contents/MacOS/connector' \
  --pid 12345 --session 'SESSION-FROM-DISCOVERY' run @operation.json

'/Applications/Connector.app/Contents/MacOS/connector' \
  --pid 12345 --session 'SESSION-FROM-DISCOVERY' run - < operation.json

A successful command writes {"ok":true,"result":...} to stdout. A failed command exits with status 1 and writes {"ok":false,"error":...} to stderr. Check both the process status and JSON envelope. Do not treat a successfully launched process as a completed edit.

For subprocesses, pass arguments as an array and serialize JSON with your language's JSON library. This avoids shell quoting problems in text, filenames and JavaScript source. The Python examples implement this pattern.

Create a document

Connector 0.1.5 introduced named document creation. Check that document.create appears in the selected host's capabilities, then choose a new .hype destination with an existing writable parent:

{"op":"document.create","destination":"/absolute/output/New.hype","display":true,"timeout":120}

Confirm created:true, saved:true and the returned path before discovering layouts and elements. Creation leaves the new document open. display:false requests creation without showing its initial window. A failure or timeout can leave a document or partial output, so inspect the returned job and preserved-document details before another deliberate action. A timeout does not cancel native work.

Build a working copy

Send these as separate operations, filling later values from earlier responses:

{"op":"fixture.stage","source":"/absolute/Base.hype"}

The staging response returns path, a fresh copy. Use that exact path:

{"op":"document.open","path":"/absolute/returned-copy.hype","display":false}

Confirm opened:true before continuing. display:false suppresses the initial document window; subsequent editor actions can still display UI. Staging rejects symlinks and special files. An optional destination selects an existing staging parent already accessible to Hype, useful for large documents on an external volume.

{"op":"layout.list","document":"/absolute/returned-copy.hype"}

Use the returned layout ID as scene where required and its root symbol ID as symbol. A layout/controller ID is different from its scene-container ID. IDs belong to this document; never invent them or reuse them from another package.

{"op":"element.list","document":"/absolute/returned-copy.hype","symbol":"DISCOVERED-SYMBOL-ID","offset":0,"limit":100}

For paginated lists, follow nextOffset while hasMore is true. Insertion scripts need complete before/after inventories to identify the new element reliably.

Editing building blocks

Slash notation in the table abbreviates separate operation names; send a single exact op value. Use catalog OPERATION for required fields and supported values.

For a fixed model value:

{
  "op":"element.setAttribute",
  "document":"/absolute/returned-copy.hype",
  "symbol":"DISCOVERED-SYMBOL-ID",
  "element":"DISCOVERED-ELEMENT-ID",
  "attribute":"Width",
  "value":320
}

Read the same element with element.get afterward. Model setters do not automatically reproduce inspector adjustments, recording behavior or undo grouping. Colors use an explicit object such as {"$color":[0.2,0.24,0.68,1],"space":"srgb"}. text.set accepts HTML, so escape plain text before sending it. It does not select rich-text ranges.

editor.action provides named editor actions, including insertion, duplication and grouping. These change editor context and selection. Root insertion requires the scene already to be in its root editing context; clearing element selection does not leave a nested group or symbol.

Composed editing operations

Connector 0.1.5 introduced three operations that combine preparation, current-value checks and verification. They appear in capabilities only when the loaded plugin supplies their prerequisites. Discover the real IDs before using these examples:

{"op":"element.edit","document":"/absolute/Working.hype","scene":"DISCOVERED-LAYOUT-ID","symbol":"DISCOVERED-SYMBOL-ID","timeline":"kTimelineDefaultIdentifier","element":"DISCOVERED-ELEMENT-ID","property":"Top","value":80}

element.edit reads a fresh inspector value and writes with recording disabled. An optional expectedValue adds your own guard. This is suitable for the inspector's supported geometry, typography and other property families.

{"op":"scene.configure","document":"/absolute/Working.hype","scene":"DISCOVERED-LAYOUT-ID","property":"width","applyToMatchingLayouts":false,"value":640}

scene.configure edits one selected-layout setting. Size and scaling require applyToMatchingLayouts:false. Changing a scene's dimensions does not resize its elements.

{"op":"animation.create","document":"/absolute/Working.hype","scene":"DISCOVERED-LAYOUT-ID","symbol":"DISCOVERED-SYMBOL-ID","timeline":"kTimelineDefaultIdentifier","element":"DISCOVERED-ELEMENT-ID","property":"Left","from":40,"to":300,"seconds":3}

animation.create records a new Left, Top or Opacity lane on Main from time zero to a positive frame-aligned endpoint. It refuses an existing lane, extends timeline duration only when needed and verifies the resulting animation. Use a stopped root-scene context with the target symbol already displayed. These operations can change selection, inspector pane and playhead. Only recording mode is restored. Completed steps remain applied if a later step fails.

Read the reliable editing recipes for supported contexts, receipt handling and a complete workflow. Lower-level inspector operations remain available when you need explicit control.

Use the inspector for recording

1. Call inspector.prepare with the exact document, scene, symbol, timeline, element, property and desired time.
2. Allow the editor to settle, then call inspector.get. Use its actual seconds and presented value.
3. Send inspector.set with that value as expectedValue, the actual time, and your new value. Set recording:true when deliberately recording an animation on Main.
4. Check the receipt, then read the relevant element and animation details.

A prepared context can still be pending. A changed context or presented value is refused. Playhead time can be rounded to a native frame boundary. Use the returned time instead of assuming the requested time was retained. The animation example shows a complete baseline-then-record workflow.

Scene settings use the same prepare/read/set pattern. Dimensions and scaling require explicit applyToMatchingLayouts:false. This keeps the edit scoped to the selected layout. Preparation establishes that scope, so it is itself an intentional editor operation.

Save and export

{"op":"document.save","document":"/absolute/returned-copy.hype"}

Wait for saved:true. To write another editable package without changing the open document's URL:

{"op":"document.saveCopy","document":"/absolute/returned-copy.hype","destination":"/absolute/output/Result.hype"}

For HTML:

{"op":"document.exportHTML","document":"/absolute/returned-copy.hype","destination":"/absolute/output/Result-html"}

Use new destinations with existing parents that Hype can write. Export completion returns exported:true and the actual indexPath. Export can leave further layout or metadata changes in the editable document. If these need persisting, perform a separate explicit save after confirmed export. Open the resulting HTML in your browser to check its appearance and behavior.

After reopening a package, refresh resource IDs. Native save and layout can normalize colors, dimensions and attribute representation. Compare saved values rather than assuming every input survives unchanged.

Recipes and app command mode

recipe FILE runs a fixed steps array sequentially and stops on the first error. It is not a transaction and does not substitute IDs from earlier results. Use Python or another language when the next request depends on a returned ID.

To reuse the folder access saved by the app:

'/Applications/Connector.app/Contents/MacOS/ConnectorApp' \
  --hype-pid 12345 --hype-session 'SESSION-FROM-DISCOVERY' \
  --run-operation - < operation.json

This mode accepts one UTF-8 JSON operation, up to 64 KiB. Input must reach EOF within ten seconds before dispatch. It does not accept @FILE or recipes. The standalone CLI uses the access of its own launching process.

Failures and undo

Each operation commits separately. An outcome_unknown response or transport timeout means a mutation may have happened. Stop, preserve the working copy and inspect the affected state before another deliberate action. Never automatically repeat insert, import, save or export after uncertainty.

Undo is available for suitable editor actions through document.undoState, then document.undo with the complete returned object as expectedState. Read a fresh state before redo. These operations require a prepared root scene on the stopped Main timeline. They do not create a transaction around your script. Model setters may register no undo action, so confirm affected values and save separately.

See troubleshooting for jobs, permissions and partial results.