@shader-gallery/cli

The consumer CLI engine behind npx shader-gallery.

Most people never install this directly — they run the unscoped front-door:

npx shader-gallery add billow

which is a thin package (published from the catalog repo) that forwards to this engine. Installing @shader-gallery/cli gives you the same commands under the sg bin (npx @shader-gallery/cli add …, or sg add … when linked).

add <slug> — vendor a shader into your project

Downloads one shader from the gallery and writes it as a self-contained single-file effect: an embedded /*@shader … */ header (the catalog metadata) followed by the GLSL. This is the offline/bundled complement to fetching by slug at runtime (<ShaderGalleryBg slug="billow">) — the frag is committed into your project, so there is no runtime CDN dependency and you can edit it in place.

shader-gallery add <slug> [options]

  -o, --out <dir|file>   where to write (default ./shaders/<slug>.frag;
                         a path ending in .frag is used verbatim, else a dir)
      --base <url|dir>   catalog origin (default https://shader.gallery/cdn/shaders/);
                         pass a tunnel/localhost URL or a local catalog dir
  -f, --force            overwrite an existing file
      --stdout           print the effect to stdout instead of writing

Render the written file with the runtime via @shader-gallery/components' vanilla shader() factory, or any framework wrapper, by bundling it as raw text:

import frag from './shaders/billow.frag?raw';
import { shader } from '@shader-gallery/components';

shader(frag).mount('#bg');

The catalog frags are already fully self-contained GLSL, so a vendored frag passes sg-validate unchanged — add only prepends the header, it never rewrites the GLSL.

new <slug> — scaffold a fresh effect

Writes a valid, self-contained starter .frag you can author from. It passes sg-validate as-is and renders a live, palette-cycling background out of the box, so new + dev shows something moving immediately.

shader-gallery new <slug> [options]

  -o, --out <dir|file>   where to write (default ./<slug>.frag)
      --name <title>     display name (default derived from the slug)
      --family <name>    catalog family for the header (default Aura)
  -f, --force            overwrite an existing file
      --stdout           print the effect to stdout instead of writing

The GLSL is intentionally self-contained (no //@sg-include prelude): the prelude is only expanded at catalog-import time, so pull it in (via @shader-gallery/components' sg-import) when you promote the shader into the catalog.

dev <file.frag> — live preview with param sliders

Serves a local browser preview that renders the frag with @shader-gallery/runtime, builds a slider per declared param and a palette picker from the header, and live-reloads (re-mounting, keeping your slider values) whenever you save the file.

shader-gallery dev <file.frag> [options]

      --port <n>          port to serve on (default 5173)
      --runtime <dir|url> @shader-gallery/runtime location (default: auto-detect a
                          local checkout/node_modules; or a CDN ESM url)
      --open              open the preview in your browser

The runtime is not bundled (this package stays zero-dependency) — dev resolves it from a local checkout / node_modules, or you point --runtime at a published CDN ESM bundle.

Roadmap

add, new, and dev ship in this version. Possible later additions: a --types flag on add/new (emit a .d.ts via sg-typegen), and a shader picker when the add slug is omitted.

License

MIT © E. T. Carter. Part of shader.gallery.