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 lucide svgl                        # declare libraries + vendor locally
sigil search house                           # scoped to declared libraries, offline
sigil search github --all                    # global discovery (200+ sets via Iconify)
sigil add lucide/house+menu,svgl/github      # record in icons.json
sigil etch --output public/icons.css --format css  # standalone HTML / file://
sigil etch --output src/icons.tsx --jsx react     # generate a component module
sigil etch --output src/icons.tsx --jsx react --atlas  # also generate src/icons.atlas.tsx
sigil etch --output src/icons --jsx octane --atlas     # Octane → icons.tsrx + atlas
sigil etch --output src/icons --jsx tsrx --atlas        # also generate src/icons.atlas.tsrx
sigil etch --output src/icons --jsx tsrx          # ripple-ts → src/icons.tsrx
sigil etch --output public/svg                    # no --jsx → dump 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 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 without arguments prints the same source list for quick discovery.

Ref DSL

+ joins icons, , (or a space) separates sets:

sigil add lucide/a+b,mdi/c

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.