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.
| Source | Read as |
|---|---|
code.css, code.cssd | the code of one doodle, as written between <css-doodle> tags |
https://css-doodle.com/d/:id | the code of a public doodle shared on this site |
page.html, page.htm | a page containing <css-doodle> elements; render only |
https://codepen.io/user/pen/id | the 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.
| Option | Effect |
|---|---|
--seed <seed> | seed for the random functions, to get the same result again |
--fullscreen | open the window in fullscreen |
--show-fps-counter | overlay a frame-rate counter |
--show-paint-rects | highlight 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.
| Option | Meaning | Default |
|---|---|---|
-o, --output <file> | output file name; its extension selects the format, missing directories are created | derived from the source |
-f, --format <format> | png, webp or jpeg for images, mp4 for videos | png, or mp4 with -t |
-x, --scale <n> | device scale factor, up to 10 | 2 for images, 1 for videos |
-w, --window <size> | window size as WIDTHxHEIGHT, up to 8192x8192 | 1600x1000 for images, 1200x800 for videos |
-s, --selector <selector> | CSS selector of the element to capture; an error when nothing matches | css-doodle |
-d, --delay <time> | wait before capturing, up to 30s | 0 |
-t, --time <time> | record a video of this length, up to 60s | 5s for video formats |
--seed <seed> | seed for the random functions; css-doodle code only, ignored for pages | random |
-y, --yes | overwrite an existing output file without asking; required outside a terminal | |
-q, --quiet | print 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.0orlatest, which is downloaded, or the path of a localcss-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 needcssd 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.