animl-cli 0.0.0-stage → 0.1.0

package/docs/CLI.md

@@ -0,0 +1,627 @@
+# Anima CLI reference
+
+<!-- Generated by tools/cli-docs.ts. Do not edit by hand. -->
+
+This reference is generated from the command table used by `anima help`.
+
+## Write
+
+### `anima new`
+
+scaffold an animation from a glyph, Glyphy project, or bundled sample
+
+**Usage**
+
+- `anima new <name> --glyph <file.svg> | --glyphy <project-dir> [-o out.animl] [--ani] [--force]`
+- `anima new <directory> --sample bell|moon|progress`
+
+**Options**
+
+- `--glyph <file.svg>` — scaffold from an SVG glyph
+- `--glyphy <project-dir>` — scaffold from a Glyphy project
+- `--sample <name>` — copy a bundled sample project
+- `-o, --out <file>` — write output to a file
+- `--ani` — write canonical JSON instead of AniML
+- `--force` — overwrite an existing scaffold output
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima new bell-copy --glyph fixtures/glyphs/bell.svg -o /tmp/bell-copy.animl` — scaffold AniML from the bell glyph
+- `anima new /tmp/anima-sample --sample bell` — copy the bundled bell project
+
+**See also:** `validate`, `inspect`, `docs authoring`
+
+### `anima fmt`
+
+format AniML or .ani canonically
+
+**Usage**
+
+- `anima fmt <file> [--write | --check]`
+
+**Options**
+
+- `--write` — replace the file with canonical formatting
+- `--check` — check formatting without writing
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima fmt examples/bell.animl --check` — verify canonical AniML formatting
+- `anima fmt examples/bell.ani` — print canonical JSON
+
+**See also:** `validate`, `decompile`
+
+### `anima import`
+
+import supported SVG or Lottie features as AniML
+
+**Usage**
+
+- `anima import <file.svg|file.json> [-o out.animl]`
+
+**Options**
+
+- `-o, --out <file>` — write output to a file
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima import fixtures/glyphs/bell.svg -o /tmp/bell-import.animl` — import the reference bell SVG
+
+**See also:** `new`, `validate`
+
+### `anima decompile`
+
+write canonical AniML from a .ani document
+
+**Usage**
+
+- `anima decompile <file.ani> [-o out.animl]`
+
+**Options**
+
+- `-o, --out <file>` — write output to a file
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima decompile examples/bell.ani -o /tmp/bell.animl` — convert the bell JSON document to AniML
+
+**See also:** `build`, `fmt`
+
+### `anima flatten`
+
+convert text to outlines
+
+**Usage**
+
+- `anima flatten <file> [--node id] [-o out.ani] [--font name=path]`
+
+**Options**
+
+- `--node <id>` — flatten only one text node
+- `-o, --out <file>` — write output to a file
+- `--font <name=path>` — install a local font for text measurement and rendering (repeatable)
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima flatten examples/bell.animl -o /tmp/bell-flat.ani` — flatten any text in the bell document
+
+**See also:** `import-font`, `build`
+
+### `anima library`
+
+maintain vendored AniML library imports
+
+**Usage**
+
+- `anima library update <file.animl> [--check]`
+
+**Options**
+
+- `--check` — report stale vendored imports without changing files
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima library update examples/bell.animl --check` — check the bell library imports
+
+**See also:** `build`, `validate`
+
+## Check
+
+### `anima validate`
+
+validate a document and print every diagnostic
+
+**Usage**
+
+- `anima validate <file> [--font name=path]`
+
+**Options**
+
+- `--font <name=path>` — install a local font for text measurement and rendering (repeatable)
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima validate examples/bell.animl` — validate the reference AniML scene
+- `anima validate examples/bell.ani --format=json` — emit machine-readable diagnostics
+
+**See also:** `inspect`, `schema`
+
+### `anima compare`
+
+compare two PNG files by RGBA pixels
+
+**Usage**
+
+- `anima compare a.png b.png [--tolerance 0..255] [-o diff.png]`
+
+**Options**
+
+- `--tolerance <0..255>` — maximum channel difference before a pixel fails (default: 0)
+- `-o, --out <file>` — write output to a file
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima compare examples/moon-toggle.png examples/moon-toggle.png` — compare an image with itself
+
+**See also:** `render`
+
+### `anima bench`
+
+measure compile and frame costs
+
+**Usage**
+
+- `anima bench <file> [-s script | -e "cmds"] [--frames N] [--font name=path]`
+
+**Options**
+
+- `-s, --script <file>` — read script commands from a file
+- `-e, --eval <cmds>` — run semicolon-separated script commands
+- `--reduced-motion` — run with reduced motion enabled
+- `--all` — include all values in snapshots
+- `--semantics` — include semantic state in snapshots
+- `--seed <N>` — set the uint32 script random seed
+- `--frames <N>` — number of frames to benchmark (default: 600)
+- `--font <name=path>` — install a local font for text measurement and rendering (repeatable)
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima bench examples/bell.animl --frames 60` — benchmark the bell for 60 frames
+
+**See also:** `sample`, `render`
+
+### `anima doctor`
+
+check Node, browsers, cache, and module wiring
+
+**Usage**
+
+- `anima doctor`
+
+**Options**
+
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima doctor` — check the local Anima toolchain
+
+**See also:** `playground`, `bundle`
+
+## See
+
+### `anima inspect`
+
+inspect document structure, animation, inputs, and wiring
+
+**Usage**
+
+- `anima inspect <file> [--summary] [--font name=path]`
+
+**Options**
+
+- `--summary` — print only wiring diagnostics
+- `--font <name=path>` — install a local font for text measurement and rendering (repeatable)
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima inspect examples/bell.animl` — inspect the reference bell
+- `anima inspect examples/bell.animl --summary` — show only wiring findings
+
+**See also:** `validate`, `schema`
+
+### `anima sample`
+
+run a script and print snapshots as JSON lines
+
+**Usage**
+
+- `anima sample <file> [-s script | -e "cmds"] [--reduced-motion] [--all] [--semantics] [--seed N] [--font name=path]`
+
+**Options**
+
+- `-s, --script <file>` — read script commands from a file
+- `-e, --eval <cmds>` — run semicolon-separated script commands
+- `--reduced-motion` — run with reduced motion enabled
+- `--all` — include all values in snapshots
+- `--semantics` — include semantic state in snapshots
+- `--seed <N>` — set the uint32 script random seed
+- `--font <name=path>` — install a local font for text measurement and rendering (repeatable)
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima sample examples/bell.animl -e "advance 0.2;snapshot"` — sample the bell after 0.2 seconds
+- `anima sample examples/bell.animl -e "semantics;snapshot --semantics"` — inspect semantic output headlessly
+
+**See also:** `session`, `docs authoring`
+
+### `anima session`
+
+run a persistent JSON-line script session
+
+**Usage**
+
+- `anima session <file> [--reduced-motion] [--all] [--semantics] [--seed N] [--font name=path]`
+
+**Options**
+
+- `--reduced-motion` — run with reduced motion enabled
+- `--all` — include all values in snapshots
+- `--semantics` — include semantic state in snapshots
+- `--seed <N>` — set the uint32 script random seed
+- `--font <name=path>` — install a local font for text measurement and rendering (repeatable)
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima session examples/bell.animl` — open a persistent session for the bell
+
+**See also:** `sample`, `bench`
+
+### `anima render`
+
+render frames, sheets, sequences, components, probes, or comparisons
+
+**Usage**
+
+- `anima render <file> -o out.svg|png|webm [--font name=path] [--at t] [-s script | -e "cmds"] [--size px]`
+- `anima render <file> --compare glyph.svg [--size px] [--tolerance 0..255] [-o diff.png]`
+- `anima render [file] [--component name] [--fit contain|cover|fill|none] [--viewport WxH] [--frames N] [--fps N] [--scale k] [--probe "x,y;x,y"] [--preset name] [--audio out.wav]`
+
+**Options**
+
+- `--font <name=path>` — install a local font for text measurement and rendering (repeatable)
+- `--browser-text` — render text through the browser font path
+- `--component <name>` — render one component as the root
+- `--fit <mode>` — fit the frame into the viewport (default: contain)
+- `--viewport <WxH>` — set output viewport dimensions
+- `--scale <k>` — scale inside the viewport, from 0 to 1 (default: 1)
+- `--probe <x,y;x,y>` — sample final PNG pixels at coordinates
+- `--preset <name>` — apply a project render preset (repeatable)
+- `--fps <N>` — sequence frame rate (default: 60)
+- `--audio <out.wav>` — mix captured audio events to WAV
+- `-s, --script <file>` — read script commands from a file
+- `-e, --eval <cmds>` — run semicolon-separated script commands
+- `--reduced-motion` — run with reduced motion enabled
+- `--all` — include all values in snapshots
+- `--semantics` — include semantic state in snapshots
+- `--seed <N>` — set the uint32 script random seed
+- `--frames <N>` — render a frame sequence
+- `-o, --out <file>` — write output to a file
+- `--at <seconds>` — advance to a nonnegative time before rendering
+- `--size <px>` — square render size (default: 240)
+- `--sheet <N>` — render a labelled contact sheet
+- `--over <seconds>` — contact-sheet time span
+- `--dark` — use the dark render look
+- `--color <slot=#hex>` — override a paint slot (repeatable)
+- `--current <#hex>` — override currentColor
+- `--background <#hex>` — set the output background
+- `--compare <file.svg>` — compare one rendered frame with an SVG glyph
+- `--tolerance <0..255>` — comparison channel tolerance (default: 0)
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima render examples/bell.animl -o /tmp/bell.svg` — render the bell to SVG
+- `anima render examples/bell.animl -o /tmp/bell.png --size 256` — render a 256px PNG
+- `anima render examples/bell.animl --compare fixtures/glyphs/bell.svg` — compare the rest frame with the source glyph
+
+**See also:** `inspect`, `compare`, `docs authoring`
+
+### `anima playground`
+
+open the local live editor
+
+**Usage**
+
+- `anima playground [file.animl] [--port 4519]`
+
+**Options**
+
+- `--port <N>` — local HTTP port (default: 4519)
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima playground examples/bell.animl --port 4519` — edit the bell in the local playground
+
+**See also:** `doctor`, `render`
+
+### `anima docs`
+
+read the authoring guide, format spec, markup spec, or module docs
+
+**Usage**
+
+- `anima docs [authoring | spec | markup | <section>] [section-slug] [--list | --full]`
+
+**Options**
+
+- `--list` — list available topics or sections
+- `--full` — print a long section in full instead of its contents first
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima docs authoring the-loop` — read the core authoring loop
+- `anima docs spec` — read the .ani format specification
+- `anima docs markup` — read the AniML markup specification
+
+**See also:** `schema`, `features`, `search`
+
+### `anima schema`
+
+inspect registry fields, types, spellings, and JSON Schema
+
+**Usage**
+
+- `anima schema [type | fill | stroke | a11y | timeline | layer | state | pose | transition | listener | input] [--all | --json-schema]`
+- `anima schema --search <words> | <type>.<field> [--animatable] [--bindable] [--inherited] [--editor-only]`
+
+**Options**
+
+- `--search <words>` — search registry names and diagnostic codes
+- `--animatable` — show animatable fields only
+- `--bindable` — show bindable fields only
+- `--inherited` — show inherited fields only
+- `--editor-only` — show editor-only fields when applicable
+- `--all` — print every type and field instead of the topic index
+- `--json-schema` — print the complete generated JSON Schema
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima schema rect` — inspect rectangle fields and spellings
+- `anima schema listener --format=json` — inspect listener fields as JSON
+- `anima schema --search width` — search schema vocabulary
+
+**See also:** `docs`, `search`
+
+## Find
+
+### `anima features`
+
+list capabilities provided by Anima features
+
+**Usage**
+
+- `anima features [name]`
+
+**Options**
+
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima features` — list all feature names and summaries
+- `anima features paint` — show what the paint feature provides
+
+**See also:** `search`, `examples`, `docs`
+
+### `anima search`
+
+search the capability index
+
+**Usage**
+
+- `anima search <words…> [--kind k] [--limit n]`
+
+**Options**
+
+- `--kind <k>` — limit results to one or more entry kinds (repeatable)
+- `--limit <n>` — maximum result count (default: 10)
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima search "hover effect"` — find capabilities related to hover
+- `anima search ik --kind capability --limit 5` — find IK capability rows
+
+**See also:** `features`, `examples`, `docs`, `schema`
+
+### `anima examples`
+
+find, print, or copy example scenes
+
+**Usage**
+
+- `anima examples [topic|name] [--print | -o dir]`
+
+**Options**
+
+- `--print` — print one matching example file
+- `-o, --out <dir>` — copy one matching example into a directory
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima examples bell` — find bell examples
+- `anima examples bell --print` — print the matching bell example
+
+**See also:** `features`, `search`
+
+### `anima help`
+
+show overview, command help, or the command table
+
+**Usage**
+
+- `anima help [command] [--all] [--json]`
+
+**Options**
+
+- `--all` — include hidden commands in the overview
+- `--json` — print the command table as JSON
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima help` — show the grouped command overview
+- `anima help render` — show render usage, options, and examples
+- `anima help --json` — print the machine-readable command table
+
+**See also:** `features`, `search`
+
+## Ship
+
+### `anima build`
+
+compile AniML or export a self-contained local web build
+
+**Usage**
+
+- `anima build <file.animl|page.html> [-o out] [--embed] [--font name=path]`
+- `anima build [file] --out-dir <directory> [--font name=path]`
+
+**Options**
+
+- `-o, --out <file>` — write output to a file
+- `--out-dir <directory>` — export .ani, runtime, and HTML into a directory
+- `--embed` — embed build assets into the compiled document
+- `--font <name=path>` — install a local font for text measurement and rendering (repeatable)
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima build examples/bell.animl -o /tmp/bell.ani` — compile the bell to canonical JSON
+- `anima build examples/bell.animl --out-dir /tmp/bell-site` — export a local web build
+
+**See also:** `bundle`, `validate`
+
+### `anima bundle`
+
+bundle selected browser runtime modules
+
+**Usage**
+
+- `anima bundle [--modules paint,bind] [-o anima.js] [--verbose]`
+
+**Options**
+
+- `--modules <name,name>` — comma-separated runtime modules
+- `-o, --out <file>` — write output to a file
+- `--verbose` — print module size detail
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima bundle --modules paint,bind -o /tmp/anima.js` — bundle the paint and bind runtime modules
+
+**See also:** `build`, `doctor`
+
+### `anima completion`
+
+generate shell completion from the command table
+
+**Usage**
+
+- `anima completion bash|zsh|fish`
+
+**Options**
+
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima completion bash` — print Bash completion source
+
+**See also:** `help`
+
+### `anima version`
+
+print the CLI package version
+
+**Usage**
+
+- `anima version`
+
+**Options**
+
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima version` — print the installed CLI version
+
+**See also:** `help`
+
+## Fonts and assets
+
+### `anima import-font`
+
+store, subset, or fetch a font at build time
+
+**Usage**
+
+- `anima import-font <font> -o local.ttf [--chars "ABC"]`
+- `anima import-font --google "Family:wght@400;600" -o local.ttf [--chars "ABC"]`
+
+**Options**
+
+- `-o, --out <file>` — write output to a file
+- `--google <family:axes@values>` — fetch a Google Font at build time
+- `--chars <text>` — subset the font to these characters
+- `--format <text|json>` — output format (default: text)
+- `-h, --help` — show this command’s help
+
+**Examples**
+
+- `anima import-font fixtures/fonts/anima-test.ttf -o /tmp/anima-test.ttf --chars "Anima"` — subset the bundled test font
+
+**See also:** `flatten`, `build`