shader-cli

Agent-native CLI for Shader Lab — create, stack, and export WebGPU shader compositions from the terminal.

ASCII art shader composition — generated entirely from the CLI

CRT + Dithering + Pattern composition with custom text color (#0047ab)

CLI commands used to generate the above

bun run src/index.ts -- preset apply crt-text --text "ReScience Lab" -o scene.lab
bun run src/index.ts -- --project scene.lab layer set 2 -p "textColor=#0047ab"
bun run src/index.ts -- --project scene.lab export video -o ReScience-Lab-blue.webm

---

This is a fork of basement.studio's Shader Lab with an added CLI harness that makes the shader editor fully controllable from the command line. All project editing is instant (pure JSON). Video/image export uses headless Chrome with WebGPU.

Quick Start

git clone https://github.com/ReScienceLab/shader-cli.git
cd shader-cli

# Install editor + CLI dependencies
bun install
cd cli && bun install && cd ..

# Start the editor (needed for export)
bun run dev &

# Create a CRT text animation in one command
cd cli
bun run src/index.ts -- preset apply crt-text --text "Hello World" -o scene.lab
bun run src/index.ts -- --project scene.lab export video -o output.webm

CLI Commands

Project Management

shader-cli project new [--name "Name"] [--width 1920] [--height 1080] [-o out.lab]
shader-cli project open <path.lab>
shader-cli project save [path]
shader-cli project info
shader-cli project json

Layer Operations

shader-cli layer add <type> [-n "Name"] [-p key=value ...]
shader-cli layer remove <index>
shader-cli layer reorder <from> <to>
shader-cli layer set <index> <key> <value>
shader-cli layer set <index> -p key=value ...    # batch set
shader-cli layer list
shader-cli layer info <index>
shader-cli layer hide/show <index>
shader-cli layer types                           # list all 26 layer types
shader-cli layer params <type>                   # show parameters for a type

Scene Configuration

shader-cli scene set <key> <value>    # backgroundColor, brightness, contrast, etc.
shader-cli scene info
shader-cli scene aspect <preset>      # screen | 16:9 | 9:16 | 1:1 | custom

Timeline & Animation

shader-cli timeline duration <seconds>
shader-cli timeline loop --on/--off
shader-cli timeline keyframe add <layer> <time> <property> <value> [-i smooth]
shader-cli timeline info

Export (requires Chrome + WebGPU)

shader-cli export video [-o out.webm] [--format webm|mp4] [--quality standard] [--fps 30]
shader-cli export image [-o out.png] [--quality standard] [--time 0]
shader-cli export project [-o out.lab]

Presets

shader-cli preset list
shader-cli preset apply <name> [--text "Text"] [-o out.lab]

Built-in Presets

Preset	Description	Layers
crt-text	Retro CRT monitor with dithering, pattern, and gradient	5
neon-glow	Glowing neon text with ink bleed	3
ascii-art	ASCII art style with gradient	3
halftone-print	CMYK halftone printing effect	3
pixel-sort	Pixel sorting glitch effect	3
circuit-bent	Scanline circuit-bent CRT look	3

Layer Types

Source layers: text, gradient, image, video, custom-shader, live

Effect layers: crt, dithering, ascii, pattern, halftone, ink, particle-grid, pixelation, pixel-sorting, posterize, threshold, directional-blur, smear, fluted-glass, plotter, circuit-bent, slice, edge-detect, displacement-map, chromatic-aberration

Example Workflows

Build from scratch

bun run src/index.ts -- project new -o my.lab
bun run src/index.ts -- --project my.lab layer add gradient -p preset=neon-glow -p animate=true
bun run src/index.ts -- --project my.lab layer add text -p "text=ReScience Lab" -p fontSize=201
bun run src/index.ts -- --project my.lab layer add dithering -p algorithm=bayer-4x4
bun run src/index.ts -- --project my.lab layer add crt -p bloomEnabled=true
bun run src/index.ts -- --project my.lab export video -o output.webm

Agent JSON mode

bun run src/index.ts -- --json layer types
bun run src/index.ts -- --json layer params crt
bun run src/index.ts -- --json --project my.lab layer set 2 -p bloomIntensity=3.0
bun run src/index.ts -- --json --project my.lab project info

REPL mode

bun run src/index.ts
# Enters interactive shell with undo/redo support

Architecture

shader-cli/
├── cli/                    # CLI harness (this fork's addition)
│   ├── src/
│   │   ├── index.ts        # Entry + REPL
│   │   ├── commands/       # project, layer, scene, timeline, export, preset
│   │   ├── core/           # project-engine, layer-registry, session
│   │   └── utils/          # output formatting, REPL
│   └── skills/SKILL.md     # Agent skill definition
├── src/                    # Shader Lab editor (upstream)
│   ├── app/                # Next.js App Router
│   ├── components/         # Editor UI
│   ├── lib/                # Config, export logic
│   └── renderer/           # WebGPU shader passes
└── packages/
    └── shader-lab-react/   # @basementstudio/shader-lab runtime

Key design: All project/layer/scene/timeline commands are pure JSON operations (millisecond-level). Only export commands launch a browser with WebGPU for rendering.

Requirements

• Bun >= 1.3
• Chrome/Chromium with WebGPU support (for export)
• Playwright (for headless export)

Credits

• Shader Lab by basement.studio — the underlying shader editor and @basementstudio/shader-lab runtime
• CLI-Anything by HKUDS — inspiration for the agent harness architecture

License

Apache-2.0 — same as upstream Shader Lab.