@svgforge/svgforge-cli

@svgforge/svgforge-cli

Command line interface for svgforge — create optimized SVG sprites of several types along with accompanying stylesheet resources and example documents.

The configuration options are documented in the svgforge library.

There is a Github page with some tutorials.

Installation

Install globally to use svgforge anywhere:

npm install --global @svgforge/svgforge-cli

Or as a project dependency (e.g. for usage in npm scripts):

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.

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:

svgforge --view --view-example --view-bust=false --dest=out assets/*.svg

Create a symbol sprite with an accompanying CSS stylesheet and example document:

svgforge --symbol --symbol-render-css --symbol-example --dest=out assets/*.svg

Add a 10px padding around all shapes of a stack sprite:

svgforge --stack -p 10 assets/*.svg

Instead of passing options on the command line you can also use an external JSON config file:

svgforge --config config.json assets/*.svg

Tip: A config file can be generated with AI DeepWiki online configurator.

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:

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:

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.

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 — the underlying sprite creation library
• svgforge docs — detailed documentation of all sprite modes

License

MIT © svgforge