Skip to content

keryx storyboard migrate

Description

Rewrite a storyboard onto the current schema.

keryx's storyboard format changes occasionally. Where a change can be applied mechanically, it becomes a migration rather than something you edit by hand — storyboard migrate applies every pending one to a workspace's storyboard.json.

It is safe to run repeatedly: a board already on the current schema is left untouched, and the command says so.

Usage

keryx storyboard migrate <slug> [flags]
keryx storyboard migrate --all

Flags

Flag Description Default Required
--all migrate every workspace under the reel root false
--dry-run report what would change without writing false

Run keryx storyboard migrate --help for the authoritative, always-current flag set.

What it does

Start with --dry-run — it prints exactly which cards would change and writes nothing:

$ keryx storyboard migrate --all --dry-run
a-website-for-the-place-i-still-call-home: cover-to-illustration — card(s) [1]
everyone-reads-your-config: cover-to-illustration — card(s) [1]
nobody-told-it-to: cover-to-illustration — card(s) [1 9]
sandboxed-isnt-safe: cover-to-illustration — card(s) [1]

5 card(s) would change. Re-run without --dry-run to write them.

Then run it for real. It rewrites files you have committed, so review the diff before committing — the output above tells you exactly where to look.

Migrations

cover-to-illustration

The cover is a full-bleed illustration now, not a thumbnail above the text.

A card used to be able to set cover: true, which scaled the reel's cover art into a box above the words. That treatment came from the original Python scripts, written before overlay cards existed, and it threw away most of the artwork's resolution to make room for text.

An overlay card already does the job properly: the illustration fills the frame, a scrim keeps the text legible over it, and nothing is scaled down. So the migration turns

{ "text": "It broke out.", "bg": "charcoal", "cover": true }

into

{
  "text": "It broke out.",
  "bg": "charcoal",
  "mode": "overlay",
  "media": { "kind": "image", "source": "cover", "path": "cover.png" }
}

A card that already has its own illustration keeps it. The dead cover flag is dropped, but nothing overwrites an image you chose — losing that to a migration would be worse than leaving one bookend unconverted.

Safety

  • --dry-run writes nothing, and prints the same report the real run does.
  • A board that would become invalid is not written. The command validates after migrating and refuses, rather than leaving you with a broken reel.
  • Re-running is safe. Migrations detect their own work and skip it.
  • A workspace with no storyboard is skipped, not treated as an error — under --all, one half-started reel must not stop the others.

See also