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.

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.3.0