SDK CLI reference

The authoring CLI ships inside hypercolor and runs from a scaffolded effect workspace. It compiles your TypeScript and GLSL into self-contained HTML artifacts, validates them, and installs them so the daemon can pick them up. This page is the exhaustive reference for every command, flag, exit code, and environment variable.

#Invocation

Inside a scaffolded workspace the CLI is wired three ways, all equivalent:

# Through the package script (the scaffold defines these)
bun run build

# Through bunx, resolving the hypercolor bin
bunx hypercolor build

# Directly against the source entrypoint (what build:effects uses in-repo)
bun run packages/core/src/cli.ts build

The bin name is hypercolor and resolves through the workspace’s hypercolor dependency. The companion scaffolder is a separate package, create-hypercolor, invoked as create-hypercolor-effect and covered in its own section below.

Run with no command, --help, or help to print usage:

bunx hypercolor --help

hypercolor <command>

Commands:
  build      Build effect entrypoints into HTML artifacts
  validate   Validate built HTML artifacts
  install    Install HTML artifacts into the user effects directory
  add        Scaffold a new effect inside the workspace

#Command map

graph TD
    ADD["add: scaffold an effect"] --> BUILD["build: compile to HTML"]
    BUILD --> VALIDATE["validate: check artifacts"]
    VALIDATE --> INSTALL["install: ship to the daemon or user dir"]

The everyday loop is add to create an effect, build to compile it, validate to confirm the artifact is well-formed, then install to deliver it. Those four are the whole surface; there is no preview-server command.

#build

Compile effect entrypoints into self-contained HTML artifacts. Each effects/<id>/main.ts (or faces/<id>/main.ts) becomes one HTML file in the output directory, with the JS bundle, inlined shader source, palette tables, and <meta> control metadata all baked in. Display-face font controls can load selected Google Fonts at runtime unless capture mode disables remote fonts.

# Build everything the workspace discovers
bunx hypercolor build --all

# Build one effect by entrypoint path
bunx hypercolor build effects/my-effect/main.ts

With no positional path and no --all, the CLI builds all discovered entrypoints anyway: an empty positional list implies --all.

#Flags

--entry-root is repeatable, which is how the in-repo build:effects script builds effects and faces in one pass:

bun run hypercolor build --all \
  --workspace-root . \
  --entry-root src/effects \
  --entry-root src/faces \
  --out ../effects/hypercolor \
  --sdk-alias-path packages/core/src/index.ts \
  --prune

#Output

On success each artifact prints a line: a ✓ for canvas and shader effects, a 💎 for display faces, followed by the effect id, the output path, and the artifact size in KB.

✓ my-effect → dist/my-effect.html (42.3 KB)
💎 now-playing → dist/now-playing.html (58.1 KB)

#validate

Check one or more built HTML artifacts for the required render surface, title, and script. Validation runs automatically before every install, but you can run it standalone, for example in CI against dist/*.html.

bunx hypercolor validate dist/*.html
bunx hypercolor validate dist/my-effect.html --strict
bunx hypercolor validate dist/my-effect.html --json

At least one file is required. With no files the CLI prints the usage line and exits non-zero.

#Flags

#Human output

Each file reports a PASS/FAIL header, then one WARN line per warning and one FAIL line per error, then a final result with the warning count:

dist/my-effect.html

PASS  Render surface + title + script

Result: PASS

A failing artifact lists its errors:

dist/broken.html

FAIL  Validation errors present
FAIL  Missing required render surface

Result: FAIL

#install

Validate and deliver built artifacts. By default the CLI copies artifacts into your local user effects directory; with --daemon it uploads them to a running daemon over HTTP. Both paths validate first and reject invalid artifacts.

# Local install into the user effects directory
bunx hypercolor install dist/*.html

# Upload to a running daemon
bunx hypercolor install dist/*.html --daemon

With no positional patterns, install defaults to dist/*.html. Patterns may be globs or plain paths; non-matching plain paths are silently skipped.

#Flags

#Local install path

Local artifacts land in the user effects directory, derived from XDG:

$XDG_DATA_HOME/hypercolor/effects/user/
# falls back to ~/.local/share/hypercolor/effects/user/ when XDG_DATA_HOME is unset

On a name collision the installer appends a numeric suffix (my-effect.html, my-effect-2.html) rather than overwriting. The daemon picks up new local artifacts on startup or when you ask it to rescan from the system CLI:

hypercolor effects rescan

#Daemon install path

The --daemon path POSTs each validated artifact as a multipart form (field file) to /api/v1/effects/install on the daemon base URL:

On a successful daemon install the CLI prints the installed name and control count:

✓ dist/my-effect.html → /home/you/.local/share/hypercolor/effects/user/my-effect.html (my-effect, 4 controls)

If the daemon rejects the artifact, the CLI surfaces the daemon’s error details when present, otherwise the HTTP status.

#add

Scaffold a new effect inside an existing workspace. Runs interactively when name or template is missing, prompting for the parts you didn’t pass.

bunx hypercolor add aurora --template canvas
bunx hypercolor add aurora --template shader --audio
bunx hypercolor add            # fully interactive

#Flags

When both a name and a valid --template are supplied, add runs non-interactively. Otherwise it prompts for the missing pieces. On success it prints the entry path of the new effect:

Entry: effects/aurora/main.ts

If $VISUAL or $EDITOR is set, add opens the new entrypoint in that editor.

#There is no dev command

build, validate, install, and add are the complete command set. bunx hypercolor dev takes the unknown-command path: it prints Unknown command "dev". on stderr, follows it with the usage banner, and exits 1.

The real iteration loop is build, ship, then preview inside the actual daemon or desktop app. Any guide that mentions a standalone effect preview server is stale.

#Exit codes

Every command returns a process exit code you can rely on in scripts and CI.

#Environment variables

#The scaffolder: create-hypercolor-effect

Bootstrapping a brand-new workspace is a separate package, create-hypercolor, exposed as the create-hypercolor-effect bin. The authoring hypercolor add command reuses it internally to add effects to an existing workspace.

bun create hypercolor my-effects --template canvas

create-hypercolor-effect [name] [options]

Options:
  --template <type>       Starter template: canvas, shader, face, html
  --first <effect-name>   Name of the first effect (default: my-effect)
  --audio                 Include audio-reactive starter boilerplate
  --no-git                Skip git init
  --no-install            Skip bun install
  --sdk-spec <spec>       Override the hypercolor dependency spec.
                          Defaults to the published caret range.

The scaffolder runs interactively when the workspace name or template is missing, otherwise it builds the workspace directly. It initializes git and runs bun install by default; --no-git and --no-install opt out. When finished it prints the next command: bun run build for code templates, bun run validate for the raw html template.

#Scaffolded package scripts

A fresh workspace defines the everyday commands as package scripts, so the typical loop is short bun run invocations rather than long flag strings:

#Where to go next

The dev workflow page walks the full build, validate, ship loop with screenshots and the live-preview story. The setup page covers installing Bun and scaffolding a workspace from scratch, including the file: spec for local engine checkouts. For the runtime API the CLI compiles against, see the SDK API reference page in this section. And for the daemon-facing client this CLI is deliberately not, see the system CLI reference.