CLI
The hyperbits binary ships with the npm package.
npx @av/hyperbits find [query] [--tag <tag>] [--limit <n>] [--json]npx @av/hyperbits fetch <id-or-name> [--json]npx @av/hyperbits add <name...> [--into compositions/] [--set <id=value>] [--size <WxH|9:16|1:1|16:9>] [--json]npx @av/hyperbits mcpSearch the published catalog by visual goal and tags.
npx @av/hyperbits find "gradient background"npx @av/hyperbits find "text reveal" --tag text --limit 5npx @av/hyperbits find --tag particles --json--tag is repeatable. Comma-separated values are accepted. Each result lists its variable ids (Variables: text, color, background), so you can pick a bit that exposes the knobs your design system needs. --json prints a stable object with a results array; each result carries the full variables declarations.
Print one bit record, including its variables, HTML source, helper script tag, and the embed snippet.
npx @av/hyperbits fetch fade-innpx @av/hyperbits fetch fade-in --jsonThe human output lists the variables before the source:
Variables (id, type, default, label): text string "Hello World" Text color color #fcc192 Text color background color #100f0f Background Override per instance: data-variable-values='{"text":"Hello World","color":"#fcc192","background":"#100f0f"}'--json returns the same list as bit.variables: { id, type, label, default } per entry, in declaration order.
The identifier can be the bit id (fade-in) or the exact display name (Fade In). Unknown names print close matches (Did you mean: fade-in?).
Write one or more bits into a HyperFrames project and print the snippets to embed them.
npx @av/hyperbits add fade-innpx @av/hyperbits add fade-in glitch-in --into compositions/add writes compositions/<id>.html per bit and copies the helper bundle hyperbits.iife.js next to them. After each embed snippet it prints a ready-to-edit data-variable-values example built from the bit’s declared variables:
<div data-composition-src="compositions/fade-in.html"></div><div data-composition-src="compositions/fade-in.html" data-variable-values='{"text":"Hello World","color":"#fcc192","background":"#100f0f"}'></div>Values in data-variable-values override the declared defaults for that one embed. Leave out the ids you do not change.
Theme on install with —set
Section titled “Theme on install with —set”--set id=value writes a new default into the installed copy, so every embed of that file starts from your palette without data-variable-values. It is repeatable and applies to every bit in the call that declares the id:
npx @av/hyperbits add fade-in glitch-in staggered-fade-in --into compositions/ \ --set background=#0b1020 --set color=#e8ecff --set text="Launch day"Wrote compositions/fade-in.html Set background=#0b1020 Set color=#e8ecff Set text=Launch day...Wrote compositions/staggered-fade-in.html Set background=#0b1020 Set color=#e8ecff Skipped --set text: staggered-fade-in has no "text" variable- Values are checked against the variable type:
colortakes any CSS color (#rgb,#rrggbb,rgb(),hsl(),oklch(), named colors),numbera finite number,booleantrueorfalse,stringanything. - Bits also repeat a color default as a literal in CSS and markup (
html, body,#bg,:roottokens). The literal shows when the embed outlasts the bit’s own clips, so--setrewrites those copies as well. If two variables of a bit share the same default (for examplecolorandbackgroundboth#000000inken-burns), the literals are left alone andaddprints a warning; the variable itself still applies. - Nothing is written when a bit is unknown (exit 3), a
--setis malformed or invalid, or no bit in the call declares the id (exit 2).
--json returns { "added": { ... } } for one bit and { "added": [ ... ] } for several. With --set, each record also has set (applied values), skipped (ids the bit does not declare) and, when needed, warnings.
Vertical and square output
Section titled “Vertical and square output”Every bit works at 16:9, 9:16 and 1:1. Pass --size to write the bit at the size of your host composition:
npx @av/hyperbits add fade-in --into compositions/ --size 9:16npx @av/hyperbits add card-stack --into compositions/ --size 1:1npx @av/hyperbits add carousel --into compositions/ --size 1080x1350| Value | Size |
|---|---|
9:16 | 1080x1920 (TikTok, Reels, Shorts) |
1:1 | 1080x1080 |
16:9 | 1920x1080 |
WIDTHxHEIGHT | any size, for example 1080x1350 |
--size rewrites the root data-width and data-height, the meta viewport and the html, body size. Bits size and lay themselves out from those dimensions, so a vertical bit gets a vertical layout, not a squeezed landscape frame. Without --size the bit keeps its native size (shown as Dimensions in find and fetch). The MCP tool fetch_hyperbit takes the same value as an optional size argument.
Start the hyperbits MCP server on stdio. See the MCP page.
hyperframes add
Section titled “hyperframes add”npx hyperframes add does not take a registry URL. Point a project at this catalog by setting registry in hyperframes.json to the docs site origin (the host of /registry.json and /blocks/<name>/registry-item.json), then:
npx hyperframes add fade-inhyperbits add is the guaranteed install path. The HyperFrames registry is an extra path, not a substitute.