CLI tool

Start in three commands

Install the package once, preview a file while you edit it, then render the finished doodle. The executable is available as either 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. The command is then available as cssd, or as css-doodle.

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. This makes the CLI useful in a shell pipeline as well as for saved files.

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.

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

The captured area is the element matched by -s, so the window only needs to be large enough to hold it. The pixel size of the result is the element size multiplied by the scale. 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(). 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. Also accepted as browser-path, executablePath or executable-path.

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.

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.

See also

• css-doodle/cli on GitHub
• @css-doodle/cli on npm
• export()
• Getting started