CLI tool

Start in three commands

Install the package once, open a file to edit it with a live preview, then render the finished doodle. The executable is available as either cssd or css-doodle.

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

# create or edit a doodle with a live preview
cssd artwork.css

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

Install

Install it globally with npm. Node.js 20.11 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]

Commands:
  run      Open editor to create/edit css|cssd file, or preview if no file given
  render   Generate an image from a css|cssd|html file, 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

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

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://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]

With a .css or .cssd file, opens an editor window with a live preview. The file is created when it does not exist yet, and saved edits are written back to it. With no file, opens a preview of the code from standard input.

# edit code.css with a live preview
cssd code.css

# preview only, no editor
cssd run code.css --classic

# 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 and the seed is the one the doodle rendered with, so the file can be reproduced.

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, 2s or 1m.

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

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

# 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, as mp4 and as gif
cssd render code.css -t 10s
cssd render code.css -t 10s -o loop.gif

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

gen

• cssd gen svg [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.

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

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

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 one element on it.

See also

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