Add board listing, draw.io export and bulk backup

[marnusvanwyk459]

Hi — thanks for this tool, it does the hard part (getting full-detail vector out of Miro) really well. We're using it to archive a few hundred boards, and this is what we needed on top. Happy to split it into smaller PRs if you'd prefer to take it in pieces; it's grouped into independent commits' worth of work and I've described each part separately below.

A bug worth looking at first

The wait for the Miro SDK is hard-coded to 3 seconds:

mustHaveSdk,
3_000

On every real board I tested, window.miro takes about 8.5 seconds to appear (cmd.board.api at ~4.7s, SDK at ~8.5s). So anything that addresses individual objects — all JSON export, all frame-scoped export — fails with:

Miro SDK failed to load in 3000 ms.

The timeout is now an option (sdkLoadTimeoutMs, --sdk-timeout), defaulting to 30 seconds. The existing 3-second best-effort wait is kept for the case where the SDK isn't required.

Related: whole-board SVG export previously skipped the SDK wait entirely. It now waits when it can and falls back to the old best-effort path when the SDK never loads, so the "buggy board" case in the test suite still works. On a 700-object board this took the output from 872KB to 1,022KB of vector.

Also, the CLI printed errors but exited 0, so failures were invisible to scripts. It now exits non-zero.

MIRO_TOKEN and .env

The token can come from the environment rather than --token on every invocation. Uses Node's own process.loadEnvFile, so no new dependency. Precedence is explicit token → real environment → .env. .env is git-ignored and .env.example documents the variables, including the ones the existing integration tests need.

list-boards

Lists the boards a token can reach, via the same endpoint the Miro dashboard uses. No browser, so it returns in about a second for ~190 boards. Supports table / json / ids output and a title filter.

One thing worth recording: Miro's offset paging on this endpoint is unreliable. Following nextLink from limit=25 returned 26 of 189 boards and then stopped, and nextLink disappears entirely for larger limits. So the whole list is requested in one page by default, nextLink is still followed when present, and results are de-duplicated by ID.

draw.io export (-e drawio, and an offline convert command)

Converts board objects to native mxGraph — real vertices, edges and containers, not an embedded image. Frames become containers with their children nested, sticky notes and shapes keep their fill/border/font, and connectors become edges with real source/target, arrow heads, captions and exit/entry anchors.

convert works from a saved JSON export without contacting Miro, which matters when converting many boards.

Three things Miro doesn't record, reconstructed and documented in the README:

• Z-order. The export order isn't a z-order, so large shapes used as backdrops covered their own contents. Cells are emitted largest-first (zOrder: "source" opts out).
• Font sizes. Miro stores no fontSize for sticky notes — it fits text to the note. Left alone, every sticky falls back to draw.io's 12pt default and a whole board reads as one size. Sizes are derived by wrapping at spaces and fitting to the shape; because text only breaks at spaces, the longest word sets the ceiling. Shapes and text keep the size Miro recorded.
• Curved connectors. Miro stores no waypoints, and draw.io can only curve through the points of a route, so a bare curved=1 draws a straight line. Curved connectors get an orthogonal route to smooth.

Images become labelled placeholders — the JSON export carries no image data or usable URL (all 37 on my test board have url: ""). SVG export remains the only format that preserves image content.

backup

Walks the whole board list into a timestamped directory, one directory per board, with a manifest.json recording status, attempts, paths, sizes and durations.

Serial with a configurable pause between boards, since the cost is per-board browser work rather than per API call. Each board is retried with a doubling backoff capped at five minutes; a board that exhausts its retries is recorded and the run continues rather than aborting. --resume <dir> continues an interrupted run, skipping boards that already have all their files. --dry-run shows the plan without contacting Miro.

Board titles are sanitised into directory names: slashes, colons and the characters Windows reserves are replaced, control characters stripped, trailing dots/spaces removed, names Windows reserves outright (CON, NUL, COM1…) suffixed, long titles shortened. The board ID is appended so boards sharing a title never collide.

Tests

58 new unit tests, all offline and network-free, covering token resolution, board listing (stubbed fetch), the draw.io conversion, and the backup helpers. The new live test skips itself when MIRO_TOKEN isn't set.

pnpm run lint and pnpm run build pass.

One note on CI: test:board-object-types and test:api exit 1 when TEST_BOARD_ID and friends are unset, so the on: push workflow fails on a fork, which has no access to the secrets. That's pre-existing behaviour and I left it alone rather than change a decision that looked deliberate — but I'm happy to make them skip instead if you'd like fork CI to be green.

🤖 Generated with Claude Code