@svgforge/svgforge-cli 2.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Felix Müller
+Based on svg-sprite — Copyright © 2018 Joschi Kuphal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @svgforge/svgforge-cli
+
+[![npm version][npm-image]][npm-url] [![Build Status][ci-image]][ci-url] [![Coverage Status][coveralls-image]][coveralls-url] [![npm downloads][npm-downloads]][npm-url]
+
+[Command line interface](https://github.com/svgforge/svgforge-cli) for [svgforge](https://github.com/svgforge/svgforge) — create optimized **SVG sprites** of several types along with accompanying stylesheet resources and example documents.
+
+The configuration options are [documented in the svgforge](https://github.com/svgforge/svgforge/blob/main/docs/configuration.md) library.
+
+## Installation
+
+Install globally to use `svgforge` anywhere:
+
+```bash
+npm install --global @svgforge/svgforge-cli
+```
+
+Or as a project dependency (e.g. for usage in npm scripts):
+
+```bash
+npm install --save-dev @svgforge/svgforge-cli
+```
+
+## Usage
+
+```
+svgforge [options] files
+```
+
+Run `svgforge --help` to get a full list of all available options, or consult the [command line reference](docs/command-line.md).
+
+### Examples
+
+Create a `view` sprite of all SVG files in `assets/` and write the result — along with an example HTML document — to the `out/` directory:
+
+```bash
+svgforge --view --view-example --view-bust=false --dest=out assets/*.svg
+```
+
+Create a `symbol` sprite with an accompanying CSS stylesheet and example document:
+
+```bash
+svgforge --symbol --symbol-render-css --symbol-example --dest=out assets/*.svg
+```
+
+Add a 10px padding around all shapes of a `stack` sprite:
+
+```bash
+svgforge --stack -p 10 assets/*.svg
+```
+
+Instead of passing options on the command line you can also use an external JSON config file:
+
+```bash
+svgforge --config config.json assets/*.svg
+```
+
+> **Tip:** A config file can be generated with AI DeepWiki [online configurator](https://deepwiki.com/svgforge/svgforge-cli).
+
+### Sprite modes
+
+The CLI supports all four sprite modes of svgforge. Activate them individually or combine them in a single run (e.g. `--view --symbol`):
+
+| Mode | Flag | Description |
+| ---- | ---- | ----------- |
+| `view` | `--view` / `-v` | SVG view-based sprite |
+| `symbol` | `--symbol` / `-s` | Sprite of `<symbol>` elements for inline embedding |
+| `stack` | `--stack` / `-S` | Stacked sprite with `:target` CSS |
+| `defs` | `--defs` / `-d` | Sprite of `<defs>` elements (legacy) |
+
+### Advanced globbing
+
+Some shells don't support the double-star character `**`. Wrap your glob expression in single quotes so that Node.js handles the matching instead:
+
+```bash
+svgforge --config config.json 'assets/**/*.svg'
+```
+
+The CLI typically derives shape IDs from the file basename. To start ID traversal from a base directory, add a symbolic link to that directory (`./`) to your pattern:
+
+```bash
+svgforge --config config.json 'assets/./**/*.svg'
+```
+
+This results in shape IDs like `path--to--source` (assuming the default shape ID generator is used).
+
+## Development
+
+Requirements: Node.js >= 18, [pnpm](https://pnpm.io).
+
+```bash
+pnpm install
+pnpm lint     # Run XO linter
+pnpm test     # Run the test suite (node --test)
+```
+
+The test suite spawns the CLI as a child process against fixtures in `test/fixtures/` and asserts the generated sprite files and their contents.
+
+## Related
+
+- [svgforge](https://github.com/svgforge/svgforge) — the underlying sprite creation library
+- [svgforge docs](https://github.com/svgforge/svgforge/tree/main/docs) — detailed documentation of all sprite modes
+
+## License
+
+[MIT](LICENSE) © Felix Müller
+[npm-url]: https://www.npmjs.com/package/@svgforge/svgforge-cli
+
+[npm-image]: https://img.shields.io/npm/v/@svgforge/svgforge-cli?logo=npm&logoColor=fff
+
+[npm-downloads]: https://img.shields.io/npm/dm/@svgforge/svgforge-cli
+[ci-url]: https://github.com/svgforge/svgforge-cli/actions/workflows/test.yml?query=branch%3Amain
+[ci-image]: https://img.shields.io/github/actions/workflow/status/svgforge/svgforge-cli/test.yml?branch=main&label=CI&logo=github
+
+[coveralls-url]: https://coveralls.io/github/svgforge/svgforge-cli?branch=main
+[coveralls-image]: https://img.shields.io/coveralls/github/svgforge/svgforge-cli/main?logo=coveralls

package/bin/config.yaml

@@ -0,0 +1,427 @@
+dest:
+  description: Main output directory (base path)
+  alias: D
+  default: .
+  map: dest
+
+config:
+  description: Path to external JSON config file
+  alias: C
+
+log:
+  description: Logging verbosity ("info", "verbose" or "debug")
+  alias: l
+  map: log
+
+shape:
+  id:
+    separator:
+      description: Separator for traversing a directory structure into a shape ID
+      default: --
+      map: shape.id.separator
+
+    generator:
+      description: ID generation callback [via CLI only template strings]
+      default: "%s"
+      map: shape.id.generator
+
+    pseudo:
+      description: Separator for CSS pseudo classes
+      default: "~"
+      map: shape.id.pseudo
+
+    whitespace:
+      description: Whitespace replacement string for shape IDs
+      default: "_"
+      map: shape.id.whitespace
+
+  dim:
+    width:
+      description: Maximum shape width in pixels
+      default: 2000
+      alias: w
+      map: shape.dimension.maxWidth
+
+    height:
+      description: Maximum shape height in pixels
+      default: 2000
+      alias: h
+      map: shape.dimension.maxHeight
+
+    precision:
+      description: Precision (decimal places) for dimension calculations
+      default: 2
+      map: shape.dimension.precision
+
+    attributes:
+      description: Whether to add width and height attributes to the shapes
+      default: false
+      map: shape.dimension.attributes
+
+  spacing:
+    padding:
+      description: Padding around shape (up to 4 x comma-separated)
+      default: 0,0,0,0
+      alias: p
+      map: shape.spacing.padding
+
+    box:
+      description: Box sizing strategy ("content", "padding" or "icon")
+      default: content
+      alias: b
+      map: shape.spacing.box
+
+  meta:
+    description: Path to YAML file with meta information
+    alias: m
+    map: shape.meta
+
+  align:
+    description: Path to YAML file with alignment information
+    alias: a
+    map: shape.align
+
+  dest:
+    description: Path to output directory for intermediate SVG files
+    alias: ims
+    map: shape.dest
+
+  transform:
+    description: Comma-separated list of predefined transformers (see docs)
+    default: svgo
+    map: shape.transform
+
+    "*":
+      description: External JSON config files for named transformers
+
+svg:
+  xmldecl:
+    description: Whether to include an XML declaration in SVG files
+    default: true
+    map: svg.xmlDeclaration
+
+  doctype:
+    description: Whether to include a doctype declaration in SVG files
+    default: true
+    map: svg.doctypeDeclaration
+
+  namespace:
+    ids:
+      description: Whether to apply ID namespacing to the sprite
+      default: true
+      map: svg.namespaceIDs
+
+    prefix:
+      description: What, if any, prefix to apply to the automatically generated id
+      default: ""
+      map: svg.namespaceIDPrefix
+
+    classnames:
+      description: Whether to apply CSS class namespacing to the sprite
+      default: true
+      map: svg.namespaceClassnames
+
+  dimattrs:
+    description: Whether to add width and height attributes to the sprite
+    default: true
+    map: svg.dimensionAttributes
+
+  rootattrs:
+    description: Custom root attributes for the outermost <svg> element (external JSON file)
+    map: svg.rootAttributes
+
+  precision:
+    description: Floating point precision for CSS positioning values
+    default: -1
+    map: svg.precision
+
+view:
+  description: Activates the «view» mode
+  default: false
+  alias: v
+
+  dest:
+    description: Mode specific output directory
+    default: view
+    map: mode.view.dest
+
+  sprite:
+    description: Sprite path and filename (relative to --view-dest)
+    default: svg/sprite.view.svg
+    alias: vs
+    map: mode.view.sprite
+
+  bust:
+    description: Enable cache busting
+    default: true
+    map: mode.view.bust
+
+  render:
+    css:
+      description: Whether to render a CSS stylesheet with shape dimension classes
+      default: false
+      alias: vcss
+
+      template:
+        description: CSS stylesheet Mustache template (relative to svgforge basedir)
+        default: tmpl/common/sprite.css
+        map: mode.view.render.css.template
+
+      dest:
+        description: CSS stylesheet destination (relative to the --view-dest)
+        default: sprite.css
+        map: mode.view.render.css.dest
+
+    "*":
+      description: Custom output renderings
+      template:
+        description: Custom output Mustache template (relative to svgforge basedir)
+
+      dest:
+        description: Custom output destination (relative to the --view-dest)
+
+  example:
+    description: Whether to render an example HTML document
+    default: false
+    alias: vx
+
+    template:
+      description: HTML document Mustache template (relative to svgforge basedir)
+      default: tmpl/view/sprite.html
+      map: mode.view.example.template
+
+    dest:
+      description: HTML document destination (relative to the --view-dest)
+      default: sprite.view.html
+      map: mode.view.example.dest
+
+defs:
+  description: Activates the «defs» mode
+  default: false
+  alias: d
+
+  dest:
+    description: Mode specific output directory
+    default: defs
+    map: mode.defs.dest
+
+  prefix:
+    description: CSS selector prefix for all shapes (including placeholders)
+    default: .svg-%s
+    map: mode.defs.prefix
+
+  dimensions:
+    description: CSS selector suffix for shape dimension rules ("" for inline)
+    default: -dims
+    map: mode.defs.dimensions
+
+  sprite:
+    description: Sprite path and filename (relative to --defs-dest)
+    default: svg/sprite.css.svg
+    alias: ds
+    map: mode.defs.sprite
+
+  bust:
+    description: Enable cache busting
+    default: false
+    map: mode.defs.bust
+
+  render:
+    css:
+      description: Whether to render a CSS stylesheet
+      default: false
+      alias: dcss
+
+      template:
+        description: CSS stylesheet Mustache template (relative to svgforge basedir)
+        default: tmpl/common/sprite.css
+        map: mode.defs.render.css.template
+
+      dest:
+        description: CSS stylesheet destination (relative to the --defs-dest)
+        default: sprite.css
+        map: mode.defs.render.css.dest
+
+    "*":
+      description: Custom output renderings
+      template:
+        description: Custom output Mustache template (relative to svgforge basedir)
+
+      dest:
+        description: Custom output destination (relative to the --defs-dest)
+
+  inline:
+    description: Create sprite variant suitable for inline embedding
+    default: false
+    alias: di
+    map: mode.defs.inline
+
+  example:
+    description: Whether to render an example HTML document
+    default: false
+    alias: dx
+
+    template:
+      description: HTML document Mustache template (relative to svgforge basedir)
+      default: tmpl/defs/sprite.html
+      map: mode.defs.example.template
+
+    dest:
+      description: HTML document destination (relative to the --defs-dest)
+      default: sprite.defs.html
+      map: mode.defs.example.dest
+
+symbol:
+  description: Activates the «symbol» mode
+  default: false
+  alias: s
+
+  dest:
+    description: Mode specific output directory
+    default: symbol
+    map: mode.symbol.dest
+
+  prefix:
+    description: CSS selector prefix for all shapes (including placeholders)
+    default: .svg-%s
+    map: mode.symbol.prefix
+
+  dimensions:
+    description: CSS selector suffix for shape dimension rules ("" for inline)
+    default: -dims
+    map: mode.symbol.dimensions
+
+  sprite:
+    description: Sprite path and filename (relative to --symbol-dest)
+    default: svg/sprite.css.svg
+    alias: ss
+    map: mode.symbol.sprite
+
+  bust:
+    description: Enable cache busting
+    default: false
+    map: mode.symbol.bust
+
+  render:
+    css:
+      description: Whether to render a CSS stylesheet
+      default: false
+      alias: sc
+
+      template:
+        description: CSS stylesheet Mustache template (relative to svgforge basedir)
+        default: tmpl/common/sprite.css
+        map: mode.symbol.render.css.template
+
+      dest:
+        description: CSS stylesheet destination (relative to the --symbol-dest)
+        default: sprite.css
+        map: mode.symbol.render.css.dest
+
+    "*":
+      description: Custom output renderings
+      template:
+        description: Custom output Mustache template (relative to svgforge basedir)
+
+      dest:
+        description: Custom output destination (relative to the --symbol-dest)
+
+  inline:
+    description: Create sprite variant suitable for inline embedding
+    default: false
+    alias: si
+    map: mode.symbol.inline
+
+  example:
+    description: Whether to render an example HTML document
+    default: false
+    alias: sx
+
+    template:
+      description: HTML document Mustache template (relative to svgforge basedir)
+      default: tmpl/symbol/sprite.html
+      map: mode.symbol.example.template
+
+    dest:
+      description: HTML document destination (relative to the --symbol-dest)
+      default: sprite.symbol.html
+      map: mode.symbol.example.dest
+
+stack:
+  description: Activates the «stack» mode
+  default: false
+  alias: S
+
+  dest:
+    description: Mode specific output directory
+    default: stack
+    map: mode.stack.dest
+
+  prefix:
+    description: CSS selector prefix for all shapes (including placeholders)
+    default: .svg-%s
+    map: mode.stack.prefix
+
+  dimensions:
+    description: CSS selector suffix for shape dimension rules ("" for inline)
+    default: -dims
+    map: mode.stack.dimensions
+
+  sprite:
+    description: Sprite path and filename (relative to --stack-dest)
+    default: svg/sprite.css.svg
+    alias: Ss
+    map: mode.stack.sprite
+
+  bust:
+    description: Enable cache busting
+    default: false
+    map: mode.stack.bust
+
+  rootviewbox:
+    description: Add viewBox attribute to root svg automatically
+    default: true
+    map: mode.stack.rootviewbox
+
+  render:
+    css:
+      description: Whether to render a CSS stylesheet
+      default: false
+      alias: Sc
+
+      template:
+        description: CSS stylesheet Mustache template (relative to svgforge basedir)
+        default: tmpl/common/sprite.css
+        map: mode.stack.render.css.template
+
+      dest:
+        description: CSS stylesheet destination (relative to the --stack-dest)
+        default: sprite.css
+        map: mode.stack.render.css.dest
+
+    "*":
+      description: Custom output renderings
+      template:
+        description: Custom output Mustache template (relative to svgforge basedir)
+
+      dest:
+        description: Custom output destination (relative to the --stack-dest)
+
+  example:
+    description: Whether to render an example HTML document
+    default: false
+    alias: Sx
+
+    template:
+      description: HTML document Mustache template (relative to svgforge basedir)
+      default: tmpl/stack/sprite.html
+      map: mode.stack.example.template
+
+    dest:
+      description: HTML document destination (relative to the --stack-dest)
+      default: sprite.stack.html
+      map: mode.stack.example.dest
+
+variables:
+  description: Path to external JSON file with Mustache variable definitions
+  map: "variables"

package/bin/svgforge.js

@@ -0,0 +1,523 @@
+#!/usr/bin/env node
+
+/**
+ Svgforge is a Node.js module for creating SVG sprites
+
+ Based on the command line interface originally written for svg-sprite
+ by Joschi Kuphal — this is a standalone fork/package of that CLI.
+
+ @see https://github.com/joeda1/svgforge-cli
+ @author Joschi Kuphal <joschi@kuphal.net> (https://github.com/jkphl)
+ @author Felix Müller
+ @copyright © 2018 Joschi Kuphal
+ @copyright © 2026 Felix Müller
+ @license MIT https://github.com/joeda1/svgforge-cli/blob/main/LICENSE
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import {fileURLToPath} from 'node:url';
+import {load} from 'js-yaml';
+import yargs from 'yargs';
+import SVGSpriter from '@svgforge/svgforge';
+import {deepMerge, isObject, zipObject} from '@svgforge/svgforge/lib/svg-sprite/utils/index.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const {version} = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf8'));
+
+/**
+ All supported sprite modes
+
+ @type {string[]}
+ */
+const MODES = ['view', 'defs', 'symbol', 'stack'];
+
+/**
+ All supported stylesheet render types
+
+ @type {string[]}
+ */
+const RENDER_TYPES = ['css'];
+
+/**
+ Yargs argument parser instance
+ */
+
+// eslint-disable-next-line jsdoc/imports-as-dependencies -- `yargs` is a declared dependency; dynamic import() is required in JSDoc types.
+/** @typedef {import('yargs').Argv} Yargs */
+
+/**
+ CLI option definition (subset of the bundled YAML configuration)
+
+ @typedef {object} OptionDefinition
+ @property {string} [description] Option description
+ @property {string} [alias] Short option alias
+ @property {unknown} [default] Default value applied when the option is omitted
+ @property {boolean} [required] Whether the option is mandatory
+ @property {string} [map] Dot-separated config key the option maps to
+ @property {object} [children] Nested option definitions keyed by their suffix
+ */
+
+/**
+ Recursively nested map of vinyl files
+
+ @typedef {{[key: string]: File | FileMap}} FileMap
+ */
+
+/**
+ Spriter configuration (subset of the SVGSpriter configuration object)
+
+ @typedef {object} SpriterConfig
+ @property {string} [dest] Main output directory
+ @property {string} [log] Logging verbosity ("info", "verbose" or "debug")
+ @property {object} [shape] SVG shape configuration
+ @property {object} [svg] SVG output configuration
+ @property {object} [mode] Sprite mode configuration
+ @property {unknown} [variables] Mustache template variables (or the path to their JSON file)
+ */
+
+/**
+ Global spriter configuration accumulated from the CLI options
+
+ @type {SpriterConfig}
+ */
+const config = {};
+
+/**
+ External JSON configuration ("--config" file) used to detect explicitly
+ requested modes, render types and examples
+
+ @type {object}
+ */
+let JSONConfig = {mode: {}};
+
+/**
+ Maps dot-separated config keys to their CLI option names
+
+ @type {{[key: string]: string}}
+ */
+const optionsMap = {};
+
+/**
+ Resolve a path relative to the installed svgforge library
+
+ Default template files (e.g. "tmpl/stack/sprite.html") ship with the
+ svgforge library package, so they are resolved against its install
+ location rather than against this CLI package.
+
+ @param {string} target Path to resolve
+ @returns {string} Resolved absolute path
+ */
+function resolveSvgForgePath(target) {
+  const libEntry = fileURLToPath(import.meta.resolve('@svgforge/svgforge'));
+  const libRoot = path.dirname(path.dirname(libEntry));
+  return path.resolve(libRoot, target);
+}
+
+/**
+ Add a command line option and recursively register all of its children
+
+ @param {Yargs} parser Yargs instance to extend
+ @param {string} name Hyphenated option name (e.g. "defs-render-css")
+ @param {OptionDefinition} option Option configuration
+ @returns {Yargs} The extended yargs instance
+ */
+function addOption(parser, name, option) {
+  let alias = name;
+
+  // If this is an option itself
+  if ('description' in option) {
+    if ('alias' in option) {
+      alias = option.alias;
+      parser = parser.alias(alias, name);
+    }
+
+    parser = parser.describe(alias, option.description);
+
+    if ('default' in option) {
+      const templated = name.endsWith('-template');
+      const defaultValue = templated ? resolveSvgForgePath(option.default) : option.default;
+      parser = parser.default(alias, defaultValue);
+
+      if (option.default === true || option.default === false) {
+        parser = parser.boolean(name);
+      }
+    } else if (option.required) {
+      parser = parser.require(alias);
+    }
+
+    if ('map' in option) {
+      optionsMap[option.map] = name;
+    }
+  }
+
+  const {description, alias: optAlias, default: optDefault, map, required, ...children} = option;
+  for (const [key, child] of Object.entries(children)) {
+    if (isObject(child)) {
+      parser = addOption(parser, `${name}-${key}`, child);
+    }
+  }
+
+  return parser;
+}
+
+/**
+ Add a value at the given key path of a configuration object
+
+ @param {object} store Configuration object to modify
+ @param {string[]} keyPath Path segments ending at the target key
+ @param {unknown} value Value to store
+ @returns {void}
+ */
+function addConfigMap(store, keyPath, value) {
+  const key = keyPath.shift();
+
+  if (keyPath.length > 0) {
+    if (!Object.hasOwn(store, key) || !isObject(store[key])) {
+      store[key] = {};
+    }
+
+    addConfigMap(store[key], keyPath, value);
+  } else {
+    store[key] = value;
+  }
+}
+
+/**
+ Recursively write files to disk
+
+ @param {FileMap} files Nested map of vinyl files
+ @returns {number} Number of written files
+ */
+function writeFiles(files) {
+  let written = 0;
+
+  for (const file of Object.values(files)) {
+    if (!isObject(file)) {
+      continue;
+    }
+
+    if (typeof file.path === 'string') {
+      fs.mkdirSync(path.dirname(file.path), {recursive: true});
+      fs.writeFileSync(file.path, file.contents);
+      ++written;
+    } else {
+      written += writeFiles(file);
+    }
+  }
+
+  return written;
+}
+
+/**
+ Compile the spriter and write all generated files to disk
+
+ @param {SVGSpriter} spriter Spriter instance to compile
+ @returns {Promise<number>} Promise resolving to the number of written files
+ */
+function compile(spriter) {
+  return new Promise((resolve, reject) => {
+    spriter.compile((error, result) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve(writeFiles(result));
+      }
+    });
+  });
+}
+
+/**
+ Register all CLI options from the bundled YAML configuration
+
+ @returns {Yargs} The fully configured yargs instance
+ */
+function registerOptions() {
+  const parser = yargs(process.argv.slice(2))
+    .usage('Create one or multiple sprites of the given SVG files, optionally along with some stylesheet resources.\nUsage: $0 [options] files')
+    .version(version)
+    .help('help', 'Display this help information')
+    .wrap(null)
+    .example('$0 --view --view-example --dest=out assets/*.svg', 'Create a view sprite of the given SVG files including example document to the subdirectory "out"')
+    .example('$0 --defs --defs-render-css --defs-example --dest=out assets/*.svg', 'Create a defs sprite of the given SVG files including a CSS stylesheet and example document')
+    .example('$0 -S -p 10 assets/*.svg', 'Create a stack sprite and add 10px padding around all shapes')
+    .showHelpOnFail(true)
+    .demandCommand(1);
+
+  try {
+    const options = load(fs.readFileSync(path.resolve(__dirname, 'config.yaml'), 'utf8'));
+    for (const [key, option] of Object.entries(options)) {
+      addOption(parser, key, option);
+    }
+  } catch (error) {
+    console.log(error);
+  }
+
+  return parser;
+}
+
+/**
+ Apply all CLI arguments to the global configuration object
+
+ @param {SpriterConfig} cfg Configuration object to modify
+ @param {{[key: string]: string}} optMap Config keys mapped to option names
+ @param {object} argv Parsed command line arguments
+ @returns {void}
+ */
+function applyCliOptions(cfg, optMap, argv) {
+  for (const [configKey, optionName] of Object.entries(optMap)) {
+    if (!Object.hasOwn(argv, optionName)) {
+      continue;
+    }
+
+    addConfigMap(cfg, configKey.split('.'), argv[optionName]);
+  }
+}
+
+/**
+ Load an external JSON configuration file ("--config") and merge it in
+
+ @param {SpriterConfig} cfg Configuration object to merge into
+ @param {object} argv Parsed command line arguments
+ @returns {void}
+ */
+function loadExternalConfig(cfg, argv) {
+  if (!argv.config) {
+    return;
+  }
+
+  try {
+    const configFile = argv.config;
+    delete argv.config;
+    delete argv.C;
+
+    const JSONConfigContent = fs.readFileSync(path.resolve(configFile));
+    /** @type {SpriterConfig} */
+    const externalConfig = JSON.parse(JSONConfigContent);
+
+    // Keep an un-merged clone for the later option-removal checks
+    JSONConfig = JSON.parse(JSONConfigContent);
+    if (!('mode' in JSONConfig)) {
+      JSONConfig.mode = {};
+    }
+
+    // Expand shorthand mode definitions
+    if ('mode' in externalConfig && isObject(externalConfig.mode)) {
+      for (const [mode, modeConfig] of Object.entries(externalConfig.mode)) {
+        if (modeConfig !== true) {
+          continue;
+        }
+
+        externalConfig.mode[mode] = {render: {css: true}};
+        JSONConfig.mode[mode] = {render: {css: true}};
+      }
+    }
+
+    deepMerge(cfg, externalConfig);
+  } catch (error) {
+    console.error('[ERROR] Skipping --config file due to errors ("%s")', error.message.trim());
+  }
+}
+
+/**
+ Read a shape transform configuration file to a plain object
+
+ @param {string} file Path to the transform configuration file
+ @returns {object|undefined} Parsed configuration, or nothing on error
+ */
+function readTransformConfig(file) {
+  try {
+    if (fs.existsSync(file)) {
+      const contents = fs.readFileSync(file, 'utf8');
+      return contents.trim() ? JSON.parse(contents) : {};
+    }
+  } catch {
+    return undefined;
+  }
+
+  return undefined;
+}
+
+/**
+ Refine the shape related configuration options
+
+ @param {SpriterConfig} cfg Configuration object to modify
+ @param {object} argv Parsed command line arguments
+ @returns {void}
+ */
+function refineShapeConfig(cfg, argv) {
+  // Refine particular config options
+  cfg.shape.spacing.padding = String(cfg.shape.spacing.padding).trim();
+  cfg.shape.spacing.padding = cfg.shape.spacing.padding.length > 0
+    // eslint-disable-next-line unicorn/prefer-number-coercion -- Padding values may carry unit suffixes (e.g. "48px"); parseFloat is the required semantics.
+    ? cfg.shape.spacing.padding.split(',').map(dimension => Number.parseFloat(dimension || 0))
+    : [];
+
+  if (cfg.svg.rootAttributes && typeof cfg.svg.rootAttributes === 'string') {
+    try {
+      const attributesPath = path.resolve(cfg.svg.rootAttributes);
+      cfg.svg.rootAttributes = JSON.parse(fs.readFileSync(attributesPath, 'utf8'));
+    } catch (error) {
+      console.error('[ERROR] Skipping --svg-rootattrs file due to errors ("%s")', error.message.trim());
+      cfg.svg.rootAttributes = {};
+    }
+  }
+
+  // Expand transformation options
+  if (typeof cfg.shape.transform === 'string') {
+    const transforms = String(cfg.shape.transform).trim();
+    cfg.shape.transform = [];
+
+    if (transforms.length > 0) {
+      for (const raw of transforms.split(',')) {
+        const transform = String(raw).trim();
+        if (transform.length === 0) {
+          continue;
+        }
+
+        if (Object.hasOwn(argv, `shape-transform-${transform}`)) {
+          const transformConfig = readTransformConfig(argv[`shape-transform-${transform}`]);
+          // eslint-disable-next-line max-depth -- Per-transform config lookup nests the mode/shape refinement walk one level too deep.
+          if (transformConfig !== undefined) {
+            cfg.shape.transform.push(zipObject([transform], [transformConfig]));
+          }
+        } else {
+          cfg.shape.transform.push(transform);
+        }
+      }
+    }
+  }
+}
+
+/**
+ Refine the sprite mode configuration and remove inactive render types
+
+ @param {SpriterConfig} cfg Configuration object to modify
+ @param {object} argv Parsed command line arguments
+ @returns {void}
+ */
+function refineSpriteModes(cfg, argv) {
+  // Run through all sprite modes
+  for (const mode of MODES) {
+    if (argv[mode] !== true && !Object.hasOwn(JSONConfig.mode, mode)) {
+      delete cfg.mode[mode];
+      continue;
+    }
+
+    const {render} = cfg.mode[mode];
+
+    // Remove excessive render types
+    if (render) {
+      for (const renderType of RENDER_TYPES) {
+        const arg = `${mode}-render-${renderType}`;
+        if (
+          Object.hasOwn(render, renderType)
+          && argv[arg] !== true
+          && (!Object.hasOwn(JSONConfig.mode, mode)
+            || !Object.hasOwn(JSONConfig.mode[mode], 'render')
+            || !Object.hasOwn(JSONConfig.mode[mode].render, renderType))
+        ) {
+          delete render[renderType];
+        }
+      }
+    }
+
+    if (Array.isArray(cfg.mode[mode].dimensions) && cfg.mode[mode].dimensions.length === 0) {
+      cfg.mode[mode].dimensions = true;
+    }
+  }
+}
+
+/**
+ Remove excessive example options from the sprite modes
+
+ @param {SpriterConfig} cfg Configuration object to modify
+ @param {object} argv Parsed command line arguments
+ @returns {void}
+ */
+function removeExcessiveExamples(cfg, argv) {
+  for (const [mode, modeConfig] of Object.entries(cfg.mode)) {
+    const example = `${mode}-example`;
+    if (argv[example] !== true && (!Object.hasOwn(JSONConfig.mode, mode) || !Object.hasOwn(JSONConfig.mode[mode], 'example')) && Object.hasOwn(modeConfig, 'example')) {
+      delete modeConfig.example;
+    }
+  }
+}
+
+/**
+ Read and parse the Mustache variables JSON file
+
+ @param {SpriterConfig} cfg Configuration object to modify
+ @returns {void}
+ */
+function loadVariables(cfg) {
+  if (!Object.hasOwn(cfg, 'variables')) {
+    return;
+  }
+
+  const variables = String(cfg.variables).trim();
+  delete cfg.variables;
+
+  if (variables.length > 0) {
+    const variablesFile = path.resolve(variables);
+    if (fs.existsSync(variablesFile)) {
+      try {
+        cfg.variables = JSON.parse(fs.readFileSync(variablesFile, 'utf8'));
+      } catch (error) {
+        console.error('[ERROR] Skipping --variables file due to errors ("%s")', error.message.trim());
+      }
+    }
+  }
+}
+
+/**
+ Run the command line interface
+
+ @returns {Promise<void>} Promise resolving after all sprites were written
+ */
+async function main() {
+  const parser = registerOptions();
+  const argv = parser.parse();
+
+  // Map all arguments to a global configuration object
+  applyCliOptions(config, optionsMap, argv);
+
+  // Load external JSON config file
+  loadExternalConfig(config, argv);
+
+  // Refine particular config options
+  refineShapeConfig(config, argv);
+  refineSpriteModes(config, argv);
+  removeExcessiveExamples(config, argv);
+  loadVariables(config);
+
+  const spriter = new SVGSpriter(config);
+  const files = argv._.flatMap(filePattern => fs.globSync(filePattern).toSorted((a, b) => b.localeCompare(a)));
+
+  for (const filePattern of files) {
+    // Glob >= 9 returns paths without the "./" prefix, so detect relative
+    // patterns from the original glob result to preserve directory structure
+    // in the shape identifiers (e.g. "nested/leaf.svg" -> "nested--leaf")
+    const isRelative = !path.isAbsolute(filePattern) && !filePattern.startsWith('../');
+    const file = path.resolve(filePattern);
+    const stat = fs.lstatSync(file);
+    let basename;
+
+    if (stat.isSymbolicLink()) {
+      basename = path.basename(fs.readlinkSync(file));
+    } else {
+      basename = isRelative ? filePattern : path.basename(file);
+    }
+
+    spriter.add(file, basename, fs.readFileSync(file));
+  }
+
+  try {
+    await compile(spriter);
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+await main();

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@svgforge/svgforge-cli",
+  "version": "2.0.0",
+  "author": "Felix Müller (https://github.com/joeda1)",
+  "contributors": [
+    "Joschi Kuphal <joschi@kuphal.net> (https://github.com/jkphl)"
+  ],
+  "description": "Command line interface for svgforge — create SVG sprites & stacks with stylesheet resources (CSS, Sass, etc.)",
+  "homepage": "https://github.com/svgforge/svgforge-cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/svgforge/svgforge-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/svgforge/svgforge-cli/issues"
+  },
+  "keywords": [
+    "svg",
+    "stack",
+    "generator",
+    "css",
+    "cli",
+    "command-line"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "svgforge": "./bin/svgforge.js"
+  },
+  "files": [
+    "bin"
+  ],
+  "dependencies": {
+    "js-yaml": "^5.4.1",
+    "@svgforge/svgforge": "^2.0.0",
+    "vinyl": "^3.0.1",
+    "yargs": "^18.1.0"
+  },
+  "devDependencies": {
+    "eslint-plugin-jsdoc": "^64.3.2",
+    "xo": "^4.0.0"
+  },
+  "scripts": {
+    "lint": "xo",
+    "fix": "xo --fix",
+    "test": "node --test test/*.test.js",
+    "test:coverage": "mkdir -p coverage && node --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info"
+  }
+}