castwrightv0.6.0

Documentation

Write a YAML file describing a terminal session; castwright compiles it to asciicast v2 and plays it as a real terminal.

castwright turns a small YAML file into a terminal demo you can put on a page. Three pieces, each doing one job:

  • a DSL you author by hand — no recording session to get right on the seventh take;
  • a compiler that turns it into asciicast v2, deterministically, so the output is a text file you can commit and read in a diff;
  • a player built on xterm.js, so what renders is an actual terminal emulator rather than coloured spans pretending to be one.

A first demo, end to end

Written in YAML, validated, built to an SVG and a cast — this terminal is the compiled result, playing. The castwright output in it is real, recorded once with exec: and --record.

Source: site/src/demos/first-demo.terminal.yaml
# Scenario: a first demo, end to end. Recorded, not written: the castwright
# commands were exec: steps, run once in a scratch project with
# `castwright build --allow-exec --record`, which replaced each with the command
# and exactly what it printed. The shown file is files/install.terminal.yaml.
version: 1
terminal:
  title: ~/my-site
  cols: 92
  rows: 24
  theme: catppuccin-mocha
steps:
  - run: cat demos/install.terminal.yaml
  - show: files/install.terminal.yaml
  - wait: 2000
  - run: castwright validate demos/install.terminal.yaml
  - wait: 600
  - run: castwright build demos/install.terminal.yaml --format svg
  - output:
      raw: |
        dist/install.svg
  - wait: 600
  - run: castwright build demos/install.terminal.yaml
  - output:
      raw: |
        dist/install.cast
  - wait: 600
  - run: du -h dist/*
  - output:
      raw: |
        4.0K	dist/install.cast
        8.0K	dist/install.svg
    delay: 4
  - wait: 2500
$ cat demos/install.terminal.yaml
version: 1
terminal:
  title: my-cli
  cols: 72
  rows: 10
  theme: catppuccin-mocha
steps:
  - run: npm install -g my-cli
  - output: |
      {green}✓{/} added 1 package in 2s
  - run: my-cli init
  - output: |
      Created {bold}my-cli.config.json{/}
  - wait: 1500
$ castwright validate demos/install.terminal.yaml
$ castwright build demos/install.terminal.yaml --format svg
dist/install.svg
$ castwright build demos/install.terminal.yaml
dist/install.cast
$ du -h dist/*
4.0K    dist/install.cast
8.0K    dist/install.svg

It is explicitly not a terminal recorder and not a terminal emulator. ANSI and VT handling is xterm.js’s job; the interchange format already exists. castwright’s own substance is the authoring language, the compiler, the player and the exporters.

From a file to every output

Focus
How castwright works
How castwright worksYou write a terminal scene as a .terminal.yaml file. Commands that should show real output run once with --allow-exec --record, which writes what they printed back into the file; a VHS .tape builds the same way. castwright compiles the scene to asciicast v2, the same bytes on every build. That one cast plays in the web player, exports to an animated SVG without script, and to GIF or MP4 through agg and ffmpeg.Write a scene → CompileReal commands → Compile: recordedCompile → Web player: .castCompile → Animated SVGCompile → GIF or MP4recorded.castWrite a scene – .terminal.yamlWrite a scene.terminal.yamlReal commands – exec: or a VHS .tape, run onceReal commandsexec: or a VHS .tape, run onceCompile – asciicast v2, same bytesCompileasciicast v2, same bytesWeb player – xterm.js, Vite, AstroWeb playerxterm.js, Vite, AstroAnimated SVG – no script, for READMEsAnimated SVGno script, for READMEsGIF or MP4 – via agg and ffmpegGIF or MP4via agg and ffmpeg

Source: packages/core/src/parser, compiler, exec, tape, exporters, cli/formats.ts; packages/player

Show chart data
Data for How castwright works
StepKindLeads to
Write a scenestartCompile
Real commandsstartCompile (recorded)
CompilestepWeb player (.cast), Animated SVG, GIF or MP4
Web playerend
Animated SVGend
GIF or MP4end
Focus
How castwright works
How castwright worksYou write a terminal scene as a .terminal.yaml file. Commands that should show real output run once with --allow-exec --record, which writes what they printed back into the file; a VHS .tape builds the same way. castwright compiles the scene to asciicast v2, the same bytes on every build. That one cast plays in the web player, exports to an animated SVG without script, and to GIF or MP4 through agg and ffmpeg.Write a scene → CompileReal commands → Compile: recordedCompile → Web player: .castCompile → Animated SVGCompile → GIF or MP4recorded.castWrite a scene – .terminal.yamlWrite a scene.terminal.yamlReal commands – exec: or a VHS .tape, run onceReal commandsexec: or a VHS .tape, run onceCompile – asciicast v2, same bytesCompileasciicast v2, same bytesWeb player – xterm.js, Vite, AstroWeb playerxterm.js, Vite, AstroAnimated SVG – no script, for READMEsAnimated SVGno script, for READMEsGIF or MP4 – via agg and ffmpegGIF or MP4via agg and ffmpeg

Source: packages/core/src/parser, compiler, exec, tape, exporters, cli/formats.ts; packages/player

Show chart data
Data for How castwright works
StepKindLeads to
Write a scenestartCompile
Real commandsstartCompile (recorded)
CompilestepWeb player (.cast), Animated SVG, GIF or MP4
Web playerend
Animated SVGend
GIF or MP4end
Focus
How castwright works
How castwright worksYou write a terminal scene as a .terminal.yaml file. Commands that should show real output run once with --allow-exec --record, which writes what they printed back into the file; a VHS .tape builds the same way. castwright compiles the scene to asciicast v2, the same bytes on every build. That one cast plays in the web player, exports to an animated SVG without script, and to GIF or MP4 through agg and ffmpeg.Write a scene → CompileReal commands → Compile: recordedCompile → Web player: .castCompile → Animated SVGCompile → GIF or MP4recorded.castWrite a scene – .terminal.yamlWrite a scene.terminal.yamlReal commands – exec: or a VHS .tape, run onceRealcommandsexec: or a VHS.tape, run onceCompile – asciicast v2, same bytesCompileasciicast v2,same bytesWeb player – xterm.js, Vite, AstroWeb playerxterm.js, Vite,AstroAnimated SVG – no script, for READMEsAnimated SVGno script, forREADMEsGIF or MP4 – via agg and ffmpegGIF or MP4via agg andffmpeg

Source: packages/core/src/parser, compiler, exec, tape, exporters, cli/formats.ts; packages/player

Show chart data
Data for How castwright works
StepKindLeads to
Write a scenestartCompile
Real commandsstartCompile (recorded)
CompilestepWeb player (.cast), Animated SVG, GIF or MP4
Web playerend
Animated SVGend
GIF or MP4end
Focus
How castwright works
How castwright worksYou write a terminal scene as a .terminal.yaml file. Commands that should show real output run once with --allow-exec --record, which writes what they printed back into the file; a VHS .tape builds the same way. castwright compiles the scene to asciicast v2, the same bytes on every build. That one cast plays in the web player, exports to an animated SVG without script, and to GIF or MP4 through agg and ffmpeg.Write a scene → CompileReal commands → Compile: recordedCompile → Web player: .castCompile → Animated SVGCompile → GIF or MP4recorded.castWrite a scene – .terminal.yamlWrite a scene.terminal.yamlReal commands – exec: or a VHS .tape, run onceRealcommandsexec: or a VHS.tape, run onceCompile – asciicast v2, same bytesCompileasciicast v2,same bytesWeb player – xterm.js, Vite, AstroWeb playerxterm.js, Vite,AstroAnimated SVG – no script, for READMEsAnimated SVGno script, forREADMEsGIF or MP4 – via agg and ffmpegGIF or MP4via agg andffmpeg

Source: packages/core/src/parser, compiler, exec, tape, exporters, cli/formats.ts; packages/player

Show chart data
Data for How castwright works
StepKindLeads to
Write a scenestartCompile
Real commandsstartCompile (recorded)
CompilestepWeb player (.cast), Animated SVG, GIF or MP4
Web playerend
Animated SVGend
GIF or MP4end

Commands whose real output you want run once with --allow-exec --record, which writes what they printed back into the file (Recipes); a VHS .tape takes the same path (VHS tapes). GIF and MP4 need agg and ffmpeg on the PATH (CLI).

Where to start

  • Installation — the three packages and which you need.
  • Quickstart — a demo on a page in about five minutes.
  • Writing demos — how the DSL fits together.
  • Recipes — a landing-page snippet, a README SVG, an error message, real commands, a VHS tape.
  • DSL reference — every key, each with a live example.
  • VHS tapes — build an existing .tape as is.

How it compares

Tool Authoring Terminal Web output
asciinema Record a real session Real VT Mature player
VHS Declarative .tape Real VT, via headless Chrome GIF only
castwright Declarative YAML (or a VHS .tape), compiled Real VT (xterm.js) Framework-agnostic player, animated SVG, GIF/MP4

The combination castwright is after: authored rather than recorded, deterministic (same input, same bytes), browser-free at build time, and web-native at output.

Edit this page on GitHub · Docs for v0.6.0