Guide

CLI tool

@css-doodle/cli previews a doodle in a window that reloads each time you save the file, and renders it to an image or a video.

Start in three commands

The command is cssd, or css-doodle.

# install once
npm install -g @css-doodle/cli

# preview, reloaded each time the file is saved
cssd artwork.css

# export a 4× PNG
cssd render artwork.css -x 4 -o artwork.png

Install

Install it globally with npm. Node.js 22.12 or later is required.

npm install -g @css-doodle/cli

For a one-off run, npx works without installing:

npx @css-doodle/cli render code.css

Rendering and previewing happen in a real browser. The CLI looks for Chrome, Chromium or Edge on the system, and downloads a copy of Chrome on first use when none is found. A specific browser can be set with config.

Commands

Usage: cssd [options] [command]

Options:
  -V, --version  output the version number
  -h, --help     display help for command

Commands:
  run            Open a window to preview the css|cssd file, default command
  render         Generate an image from a css|cssd|html file, css-doodle or CodePen link, or http(s) URL
  gen            Generate code using css-doodle generators
  config         Display/set configurations
  use            Shorthand to fetch and use a custom version of css-doodle
  parse          Print the parsed tokens, help to debug in development
  update         Update CLI to latest version

cssd <command> --help prints the options of a command. run is the default, so cssd code.css is cssd run code.css.

Source

Every command that takes a source reads css-doodle code from one of these places.

SourceRead as
code.css, code.cssdthe code of one doodle, as written between <css-doodle> tags
https://css-doodle.com/d/:idthe code of a public doodle shared on this site
page.html, page.htma page containing <css-doodle> elements; render only
https://codepen.io/user/pen/idthe pen, opened in full-page view; render only
https://…any web page; render only
omitted, or -standard input, from a pipe or a here-string
cssd render code.css
cssd render https://css-doodle.com/d/R3WhVB20fJ9fbZ1L
cssd render https://codepen.io/yuanchuan/pen/MQEeJo
cssd render <<< '@grid: 3 / 400px; background: @p(red, blue)'
echo '@grid: 3 / 400px; background: #000' | cssd render

run

  • cssd [run] [options] [source]
  • cssd preview [options] [source]

Opens a window with a preview of a .css or .cssd file, which reloads each time the file is saved. Edit the file in any editor. With a css-doodle link or standard input, the preview shows that code once. Closing the window ends the command.

OptionEffect
--seed <seed>seed for the random functions, to get the same result again
--fullscreenopen the window in fullscreen
--show-fps-counteroverlay a frame-rate counter
--show-paint-rectshighlight repainted areas
# preview code.css, reloaded on save
cssd code.css

# the same picks every time
cssd run code.css --seed 1702

# preview a piece of code
cssd run <<< '@grid: 5 / 400px; background: @p(#000, #fff)'

render

  • cssd render [options] [source]

Renders the source to an image, or to a video when -t is given or the format is a video format. Without -o the result is written to the current directory as <name>-<seed>.png, where the name is the source file name (or the last part of a URL) and the seed is the one the doodle rendered with. Pass that seed back with --seed to render the same result again.

OptionMeaningDefault
-o, --output <file>output file name; its extension selects the format, missing directories are createdderived from the source
-f, --format <format>png, webp or jpeg for images, mp4 for videospng, or mp4 with -t
-x, --scale <n>device scale factor, up to 102 for images, 1 for videos
-w, --window <size>window size as WIDTHxHEIGHT, up to 8192x81921600x1000 for images, 1200x800 for videos
-s, --selector <selector>CSS selector of the element to capture; an error when nothing matchescss-doodle
-d, --delay <time>wait before capturing, up to 30s0
-t, --time <time>record a video of this length, up to 60s5s for video formats
--seed <seed>seed for the random functions; css-doodle code only, ignored for pagesrandom
-y, --yesoverwrite an existing output file without asking; required outside a terminal
-q, --quietprint errors only

The captured area is the element matched by -s, so the window only needs to be large enough to hold it. Times are written like 500ms, 1.5s or 1m; a bare number is milliseconds.

Videos are recorded by the browser as AV1 MP4, with no other software needed. gif and webm still work but are deprecated, and need ffmpeg installed.

# code.png, at 2x
cssd render code.css

# a sharper image, and a name of your own
cssd render code.css -x 4 -o out/wallpaper.png

# render code-1702.png again
cssd render code.css --seed 1702

# webp and jpeg
cssd render code.css -f webp
cssd render code.css -o cover.jpeg

# give an animation a head start
cssd render code.css -d 2s

# ten seconds of video
cssd render code.css -t 10s
cssd render code.css -t 10s -o loop.mp4

# a specific element of a page
cssd render page.html -s '#hero css-doodle'

gen

  • cssd gen svg [--seed <seed>] [source]
  • cssd gen polygon [source]

Runs one of the css-doodle generators on the source and prints the result. svg turns the @svg syntax into SVG markup, polygon turns @shape commands into a CSS polygon(), or into shape() when they use round, which needs css-doodle 0.57.0 or later. generate is an alias of gen. --seed fixes the random functions in svg, and needs css-doodle 0.53.0 or later.

cssd gen svg <<< 'svg { viewBox: 0 0 10 10; circle { cx: 5; cy: 5; r: 4 } }'
cssd gen polygon <<< 'points: 5; r: cos(5t)'
cssd gen svg icon.css --seed 1702

config, use

  • cssd config list
  • cssd config get <field>
  • cssd config set <field> <value>
  • cssd config unset <field>
  • cssd use <version>
browserPath
Path of the browser executable to use.
css-doodle
The css-doodle to render with: a version such as 0.51.0 or latest, which is downloaded, or the path of a local css-doodle.min.js. When it is not set, the CLI uses the css-doodle it was installed with, a 0.53 release, so newer features need cssd use latest.

cssd use <version> is a shorthand for cssd config set css-doodle <version>. Both print the version they installed, so latest resolves to a number you can pin.

cssd config list
cssd config set browserPath '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
cssd config set css-doodle ./dist/css-doodle.min.js

cssd use latest
cssd use 0.51.0
cssd use css-doodle@0.51.0

parse, update

  • cssd parse [source]
  • cssd update

parse prints the parsed form of the source as JSON, which helps when a doodle is not read the way you expect. update installs the latest version of the CLI.

cssd parse <<< '@grid: 2 / 100px; background: @p(red, blue)'
cssd update

Troubleshooting

Command not found

Check the global install with npm list -g @css-doodle/cli, reinstall it, or use npx @css-doodle/cli.

No browser

When no Chrome, Chromium or Edge is found, the CLI downloads Chrome on first use, which needs network access. Point it at a browser you already have with cssd config set browserPath …; cssd config list shows which one is in use.

Blank or cropped output

Give slow content time with -d. Make sure the element you capture fits the window: raise -w rather than -x when the doodle is larger than 1600x1000. With an HTML page or a URL, -s must match an element on it. Code that relies on a newer css-doodle than the one the CLI uses can render wrong or blank; switch with cssd use latest.

See also