Skip to content

CLI reference ​

pcosmo <command> [options]

Exit codes: 0 ok, 1 spec or build errors, 2 usage error, 3 internal error.

init ​

pcosmo init [file] [--template <name>] [--list] [--force] writes a starter spec (default diagram.cosmo.json). Templates include the starter and the lesson templates.

validate ​

pcosmo validate <spec> [--json] [--strict] runs schema and semantic checks. Diagnostics have a stable code, a JSON pointer into the spec and, where possible, a suggestion. --strict treats warnings as errors.

build ​

pcosmo build <spec> [options] writes <name>.svg (animated) next to the spec. Output flags add to it:

FlagOutput
--static<name>.static.svg, the first frame
--steps<name>.steps/step-NN.svg, one per step
--interactive<name>.interactive.svg with Play, Pause and Step (works when inlined)
--png<name>.png (--scale, --time)
--gif<name>.gif (--fps, --duration)
--mp4<name>.mp4, needs ffmpeg on PATH
--no-animatedskip <name>.svg
Option
--theme light|dark|blueprint|mono|<file>built-in theme or a custom theme JSON file
--font embed|outline|systemhow text is embedded (default embed)
--speed <n>animation speed multiplier, 0 < n <= 10
--motion smil|cssparticle motion: smil (default) or CSS offset-path
-o, --out <dir>, --name <name>where and under what name to write
--no-optimizeskip the SVGO pass
--id-prefix <p>prefix for SVG ids; the default is derived from the spec
--jsonmachine-readable result

--motion css replaces the SMIL particle animation (<animateMotion>) with CSS offset-path keyframes, so the SVG has no SMIL elements. Use it when the host strips SMIL but keeps <style>; timing, particle counts and reduced-motion behaviour match smil, and static, PNG and GIF/MP4 output are unchanged.

The same spec and options always produce byte-identical files.

watch ​

pcosmo watch <spec> [build options] builds, then rebuilds when the spec changes. Press Ctrl+C to stop.

icons ​

pcosmo icons add|list|search|remove, see Icons.

examples ​

pcosmo examples lists the gallery; pcosmo examples show <name> prints a spec; pcosmo examples copy <name|all> [-o dir] copies specs.

migrate ​

pcosmo migrate <spec> migrates a spec to the current format major. Only major 1 exists, so it confirms the version.

Environment ​

VariableEffect
PCOSMO_PACKS_DIRuser icon pack directory (also --packs-dir)
CLAUDE_PLUGIN_DATAwhen set (by Claude Code), packs live in $CLAUDE_PLUGIN_DATA/icons

The default pack directory is ~/.platformcosmo/icons.

Apache-2.0. AWS, Azure, Google Cloud, Kubernetes and the brands in Simple Icons are trademarks of their owners; use does not imply endorsement.