etch-connector

AGENT: read this first. Before interacting with Etch in any way, run etch-connector --help (or npx @digital-gravy/etch-connector --help) and read the entire output. It documents the backends, commands, flags, the stdout/stderr/exit-code contract, and how to pull the current Etch docs — everything you need to drive a tab correctly. Do not call any other command until you have read it.

A tiny local bridge that lets an AI harness — Claude Code, Cowork, or any tool that can run a shell command — drive a live Etch builder tab by evaluating scripts against the etch-public-api surface (window.etch.*).

Etch's scriptable API only exists inside the browser. There is no server you can call directly. So this connector inverts the usual direction: the browser dials out to the connector over a WebSocket (the same way Chrome remote debugging works, but in reverse), and the connector relays scripts into the tab and streams the result back.

Claude Code / Cowork
      │  shell:  etch-connector eval -t homepage "return ..."
      ▼
  etch-connector  (the `serve` daemon)
      │  ▲   WebSocket  (tab dials in via etch.connectAs)
      ▼  │
  Etch builder tab  ──►  window.etch.*

Status

This is an eval relay: the harness sends a JavaScript snippet, the page runs it as an async function, and the return value + console output come back. It is not an MCP server yet — see Going to MCP.

Scripts run in a page-enforced safe mode: the script sees only etch and the standard JS built-ins. window, document, fetch, storage, eval, … are withheld.

Install & run

No install needed — run it on demand with npx (npm) or bunx (Bun):

npx @digital-gravy/etch-connector serve
# or
bunx @digital-gravy/etch-connector serve

To get the short etch-connector command on your PATH, install it globally:

npm install -g @digital-gravy/etch-connector   # or: bun install -g …
etch-connector serve

Using the connector requires a valid, active Etch license — see LICENSE.

The examples below use the bare etch-connector command; if you're running via npx/bunx instead, prefix them with npx @digital-gravy/etch-connector (or bunx …).

Use

1. Start the daemon (once)

etch-connector serve
# bridge   ws://127.0.0.1:7331
# control  http://127.0.0.1:7332

2. Connect a tab

Primary way — the AI button. Enable the AI Connector in the Etch Settings, then open an Etch builder page and click the AI button in the left sidebar. It connects this tab for you, registering it under your site name (it just calls connectAs under the hood). Click it again to disconnect.

Secondary way — the console. You can also connect manually from the browser console:

etch.connectAs('homepage');

(connectAs is part of the public API; it opens the WebSocket back to the daemon and registers this tab under the given name. Pass { port: <n> } if you started the daemon on a non-default WebSocket port.)

3. Drive it

# list connected tabs
etch-connector tabs

# run a script (value → stdout, console output → stderr).
# reference the API as `etch.*`.
etch-connector eval -t homepage "return etch.apiVersion"

# multi-line / from a file / from stdin
etch-connector eval -t homepage -f ./script.js
echo "return await etch.blocks.getTree()" | etch-connector eval -t homepage

The script body runs as an async function, so it can return a value and use top-level await. Write scripts against the etch-public-api surface via the etch binding (window is not available). Examples:

return etch.apiVersion;
return await etch.blocks.getTree();
etch.blocks.select('block-id-123');
const groups = await etch.fields.listGroupsAsync();
return groups.length;

Output contract (for agents)

eval keeps stdout clean so a harness can capture it as the result:

• stdout — the script's return value, as pretty JSON.
• stderr — forwarded console.* output, prefixed with the level, plus connector notes that carry no such prefix (the runtime banner, warnings).
• exit code — 0 success · 2 the script threw · 1 operational failure (no such tab, ambiguous target, timeout, daemon unreachable).

For AI agents

etch-connector tabs reports, per tab, which Etch runtime it is and which surfaces that runtime backs (read off etch.environment), then prints the authoring rules that follow from it: the dynamic-data model (data sources vs loops), the route tree, the content model, the media lookup, the namespaces that throw NOT_AVAILABLE, and the block types the runtime can construct. Not every runtime backs every surface, so read that before writing scripts — and branch on a capability, never on the product name. eval names the runtime it targets on stderr as a reminder, and tabs --quiet drops the prose when you are only checking that a tab is still connected.

The authoritative agent instructions live in etch-connector --help — read the entire output before interacting with Etch. It covers the backends, commands and flags, the stdout/stderr/exit-code contract, how to pull the current Etch docs (Context7 MCP or https://docs.etchwp.com/public-api), and the conventions for structuring pages (e.g. the section/container layout pattern). The public API may also expose ready-made skills for common tasks — check the docs before improvising. Project conventions for working on this repo live in AGENTS.md.

CLI

etch-connector — drive a live Etch tab from the command line

Usage:
  etch-connector serve [--ws-port 7331] [--control-port 7332] [--ws-host 127.0.0.1]
  etch-connector tabs  [--json] [--quiet] [--control-port 7332] [--cdp]
  etch-connector eval  [code] [-t|--tab name] [-f|--file path] [--timeout ms] [--cdp]
  etch-connector upload   <file…> [-t name] [--alt text] [--collection id] [--compress webp:80[:maxWidth]] [--cdp]
  etch-connector download <id…>   [-t name] [-o|--out dir|file] [--force] [--cdp]
  etch-connector shot      [-t name] [-s|--selector css] [--full] [--jpeg] [-o|--out file] [--freeze=false]   (CDP)
  etch-connector html      <selector> [-t name]                                              (CDP)
  etch-connector computed  <selector> [-t name] [--props a,b,c]                               (CDP)

Two backends:
  bridge  (default) the tab dials in via etch.connectAs(); page-sandboxed.
          Scripts see only "etch" + the standard JS built-ins.
  cdp     connect OUT to a Chrome started with --remote-debugging-port=9222.
          No daemon. Runs at DevTools privilege: full "window", plus screenshots,
          rendered HTML, and computed styles. Opt in with --cdp (or --cdp-port /
          --remote-debugging-port / --cdp-host). Target a tab with -t <url|title substring>.

Examples:
  etch-connector serve
  etch-connector tabs
  etch-connector eval -t homepage "return etch.apiVersion"
  echo "return await etch.blocks.getTree()" | etch-connector eval -t homepage
  etch-connector eval -t homepage -f ./script.js
  # CDP backend (Chrome launched with --remote-debugging-port=9222):
  etch-connector tabs --cdp
  etch-connector eval --cdp -t etch "return document.title"
  etch-connector shot --cdp -t etch -s .orbit -o orbit.png
  etch-connector computed --cdp -t etch -s .orbit__chip --props transform,animation-duration

When exactly one tab is connected, -t is optional. With several tabs you must name one.

Assets

The assets capability denotes the full API (as in Etch Studio). Runtimes may instead report individual capabilities, including alongside wpMedia:

• assetsRead: listAsync and getAsync.
• assetsUpload: uploadAsync, without compression on upload.
• assetsDownload: downloadAsync.
• assetsUpdate: updateAsync for alt and collectionIds, not filename.
• assetsDelete: deleteAsync.
• assetsCollections: list, create, update and delete collections.
• assetsCompressInPlace: compressAsync with keepOriginal absent or false.

Absent flags are false. Check tabs before choosing operations; upload needs assetsUpload and download needs assetsDownload, unless full assets is backed. The bridge carries JSON only, so the connector base64-encodes bytes.

# Upload a photo with alt text; prints the stored asset
etch-connector upload ./hero.jpg --alt "Team on the roof"

# Where the full assets capability is backed, optionally compress before upload
etch-connector upload ./hero.jpg --alt "Team on the roof" --compress webp:80:2400

# Write an asset's bytes to a file (or into a directory, under its own name)
etch-connector download 12 --out /tmp/hero.webp

upload prints the stored asset (its id is what an etch/dynamic-image mediaId takes) and download prints { id, path, bytes }. The connector rejects ordinary uploads over 24.9 MiB locally; this Studio-derived limit also applies to WordPress, which can have its own file size and MIME restrictions. With --compress, sources up to 60 MiB may go to a runtime that supports upload-time compression. --alt takes one file per command. download refuses to overwrite an existing file, or to write a name starting with ., unless --force is given (the name comes from the tab). Both default to a 4-minute timeout, since compressing a large photo in the tab is slow; --timeout overrides it. A timed-out upload may still land, so check etch.assets.listAsync() before retrying. A runtime without etch.assets fails the script with "this runtime has no etch.assets" (exit 2).

HTTP control API

The daemon also exposes a loopback HTTP API (this is the seam the CLI uses, and the same one a future MCP server would call):

Architecture

• src/protocol.ts — the wire format, mirrored from the Etch-side bridge.ts. Keep the two in sync.
• src/bridge-server.ts — BridgeServer, the transport-agnostic core: owns the sockets, tracks tabs by name, correlates requests, handles timeouts and disconnects. This is the reusable piece.
• src/control-server.ts — the HTTP control API over the core.
• src/guidance.ts — turns a tab's etch.environment descriptor into the authoring instructions for that runtime.
• src/cli.ts — the serve / tabs / eval commands.

Going to MCP later

Today this is a CLI eval relay. A future version will expose the same bridge as a proper MCP server, so an AI harness can call first-class tools (list tabs, run a script) directly instead of shelling out — without changing how you connect a tab.

Security

Two layers, neither a substitute for the other:

Transport. Everything binds to 127.0.0.1, so any local process can reach the daemon. Run it only on a trusted machine and do not expose the ports beyond loopback. The control API refuses any request carrying an Origin header — browsers always send one, local tools do not — and /eval only takes application/json, so a web page you visit cannot drive a tab through it.

Execution. Bridge mode runs the script inside a with-bound Proxy that exposes only etch plus the standard JS built-ins and throws on window, document, fetch, storage, eval, Function, … This is a guardrail, not a hardened sandbox: because the script shares the page's JS realm, a determined author can still reach globals through prototype / constructor chains (e.g. ({}).constructor.constructor). It reliably keeps casual and AI-authored scripts on the etch surface and closes the obvious escape hatches; it does not contain hostile code. For a true boundary against adversarial scripts, run the daemon only on a trusted machine.