sigil

Agent-friendly icon package manager. Manage icons like dependencies: declare them in a manifest, and codegen is a pure projection of it.

sigil sources '{}'                        # list supported libraries/sources
sigil use "{ sets: ['lucide', 'svgl'] }"  # declare libraries + vendor locally
sigil search "{ query: 'house' }"          # scoped to declared libraries, offline
sigil search "{ query: 'github', set: '*' }"   # global discovery via Iconify
sigil add "{ refs: ['lucide/house', 'lucide/menu', 'svgl/github'] }"
sigil etch "{ output: 'public/icons.css', format: 'css' }"  # standalone HTML / file://
sigil etch "{ output: 'src/icons.tsx', jsx: 'react' }"      # component module
sigil etch "{ output: 'src/icons.tsx', jsx: 'react', atlas: true }"
sigil etch "{ output: 'src/icons', jsx: 'octane', atlas: true }"  # .tsrx + atlas
sigil etch "{ output: 'src/icons', jsx: 'tsrx', atlas: true }"
sigil etch "{ output: 'src/icons', jsx: 'tsrx' }"  # Ripple TSRX
sigil etch "{ output: 'public/svg' }"               # one .svg per icon

jsx targets: react, solid, octane (Octane), and tsrx (Ripple). Octane and Ripple both emit .tsrx, but use different framework types, SVG attribute conventions, and atlas state APIs, so they remain explicit targets. Without jsx, etch dumps one .svg file per icon. Add atlas: true with any jsx target to generate a sidecar preview module (icons.atlas.tsx or icons.atlas.tsrx) that exports a searchable IconAtlas component.

format: 'css' emits one self-contained stylesheet for standalone HTML, including documents opened directly through file://:

<link rel="stylesheet" href="./icons.css" />
<span class="sigil sigil-lu-house" aria-hidden="true"></span>

<button aria-label="Home">
	<span class="sigil sigil-lu-house" aria-hidden="true"></span>
</button>

Monochrome and duotone icons render as currentColor masks; full-color sources render as authored-color background images. The stylesheet embeds every SVG as a data URL, so it loads no external SVG, font, script, or runtime dependency.

Install

Install the latest release:

curl -fsSL https://raw.githubusercontent.com/celados/sigil/main/install.sh | bash

The installer downloads the executable JS bundle from GitHub Releases to ~/.local/bin/sigil. Set SIGIL_INSTALL_DIR to choose another directory, or --version <tag> to pin a release.

Requirements: Bun (the bundle runs on the Bun runtime) and git (used to vendor icon libraries on use).

Or run from source with Bun:

bun add github:celados/sigil   # then `bunx sigil ...`

How it works

• use → search → add → etch, modeled on a package manager: declare which libraries the project uses, then work inside them.
• use blobless-sparse-clones each icon set into a user-level cache ($XDG_CACHE_HOME/sigil/icons/<set>/, default ~/.cache/sigil/icons/), then every later command runs against local files — fast, offline, and able to find icons the hosted search index hides. The cache is shared across all projects, refreshes automatically after a day, and never touches your project directory.
• etch is a deterministic, atomic projection of icons.json: any missing icon fails the whole run without writing a file.
• Component names are stable across variants (PhHouse whether weight is regular or duotone), so switching a set's variant is a one-line manifest change with zero import churn.

Run sigil sources to see the supported sources. Bundled adapters are heroicons, lucide, ph, simple-icons, svgl, and tabler; any other set falls back to the Iconify API with identical naming, so refs stay portable. sigil use '{}' prints the same source list for quick discovery.

Icon refs

Refs are explicit set/name strings. List them as array elements; there is no separator DSL:

sigil add "{ refs: ['lucide/a', 'lucide/b', 'mdi/c'] }"

Commands return structured YAML. Pass a non-default manifest with --context "{ manifest: 'path/to/icons.json' }".

Manifest (icons.json)

Grouped by set; variant, prefix, and cssMode are set-level design decisions:

{
	"ph": { "variant": "duotone", "icons": ["house", "airplane-taxiing"] },
	"lucide": { "icons": ["house", { "name": "menu", "as": "Hamburger" }] },
	"private-icons": { "cssMode": "image", "icons": ["logo"] },
}

Bundled adapters declare a safe CSS default (mask for monochrome sets, image for svgl). Long-tail or private sets require an explicit cssMode when Sigil cannot infer their color model without guessing.

See docs/design.md for the full design.

Agent skill

A single SKILL.md teaches coding agents the library-first workflow. Install it with the skill manager:

skill add celados/sigil

Develop

bun install
bun test                  # SIGIL_E2E=1 bun test runs real vendor clones
bun run check             # typecheck + test + format

Built on argc (schema-first CLI) and @iconify/utils.