CLI
v0.0.2flab is the Flab UI command-line tool. It copies component source into your project — shadcn style — rewriting imports to your aliases, resolving dependencies, and keeping local copies in sync with the registry.
How it works
Flab's registry stores each component as self-describing source: the files to copy, the npm packages they need, and the other registry items they depend on. The CLI reads that registry and writes the source into your repo, so you own the code and can read and adapt it.
Registry files import from canonical prefixes — @/ui, @/lib, @/hooks — and the CLI rewrites those to your project's aliases on the way in. That mapping lives in flab.json, so one registry serves every project regardless of folder layout.
The trade-off of any copy-in model is drift: once a file is copied, an upstream fix never reaches it on its own. That is what flab diff and flab update are for — drift stays visible and upgrading is a deliberate, reviewable choice.
Running the CLI
Run it on demand without installing, or add it as a dev dependency. It detects your package manager from the lockfile (pnpm, yarn, bun, or npm) and uses it to install dependencies.
# run on demandpnpm dlx @flabbergasted-ai/cli initnpx @flabbergasted-ai/cli init
# or install it as a dev dependency, then call `flab`pnpm add -D @flabbergasted-ai/clipnpm flab add button
# help and versionflab --helpflab --versionUpgrading the CLI
The CLI does not update itself — that is a package operation, so your lockfile stays the source of truth for which version you run. Note the distinction: flab update upgrades the components you copied in; upgrading the tool is one of the commands below.
# running on demand — @latest always fetches the newestpnpm dlx @flabbergasted-ai/cli@latest add buttonnpx @flabbergasted-ai/cli@latest add button
# installed as a dev dependencypnpm update @flabbergasted-ai/cli # within your package.json rangepnpm add -D @flabbergasted-ai/cli@latest # jump to the newest versionflab check tells you when you are behind: it compares your installed version against the one the registry was built with and prints the upgrade command. Run flab --version to see what you have now.
Quick start
Initialise once, then add components as you need them. Anything a component depends on is copied alongside it.
flab init # write flab.json, import tokens, install base depsflab add button badge card # copy components (+ their dependencies) inflab list # see everything availableflab diff # check every local copy against the registryflab update # pull upstream changes back into your copiesCommands
flab init
Set the project up for Flab: write flab.json, ensure the token layer is imported into your global stylesheet, and install the base dependencies. Idempotent — running it again leaves an existing config and import untouched.
flab initflab init --registry <url> # record a custom registry in flab.jsonAdds @import 'tailwindcss'; and @import '@flabbergasted-ai/tokens/css'; to your CSS in the right order, creating the file if it is missing.
flab add <names...>
Copy one or more components into your project. Dependencies are resolved transitively and de-duplicated, files are written with imports rewritten to your aliases, and the required npm packages are installed at their pinned versions.
flab add buttonflab add button badge cardflab add dialog --overwrite # replace files that already existflab add button --dry-run # show what would change; write nothingflab add button --path @/widgets # install under a custom ui alias this run| Flag | Effect |
|---|---|
--overwrite | Replace existing files instead of skipping them. |
--dry-run | Print the files and packages that would change, then exit without touching the filesystem or installing anything. |
--path <alias> | Override the ui alias for this invocation (e.g. @/widgets). Both the destination and the rewritten imports follow the override, so copied files stay consistent. |
If a component needs the token layer and it is not imported yet, add warns you rather than letting the component render unstyled. When a file already exists and--overwrite is not set, it is skipped and reported.
flab list
Show every component available in the registry, with its one-line description.
flab listflab search <query>
Filter the registry index by name or description. Handy once the registry has grown past a screenful.
flab search dialogflab search chartflab info <name>
Everything the registry knows about one component: where its files will land under your aliases, its npm dependencies, the registry items it depends on, and whether it needs the token layer. Works even without a flab.json, falling back to the default aliases.
flab info buttonflab diff [name]
Compare your local copies against the registry and report each file as same, changed, or missing. With a name, it checks that one component (and its dependencies); with no name, it checks every installed component so all drift surfaces at once. Exits non-zero when anything differs.
flab diff button # one componentflab diff # every installed componentflab update [names...]
alias upgradeRe-copy installed components from the registry, pulling upstream changes back into your copies. Unlike add, it only rewrites files that already exist and never introduces a component you have not installed. With no names it refreshes every installed component. npm dependencies are reinstalled only for components whose files actually changed.
flab update button # upgrade one component in placeflab update # upgrade everything installedThis is the deliberate step diff points to. Review the diff first, then update — and because the source lives in your repo, the change lands in your version control like any other edit.
flab remove <names...>
alias rmDelete a component's own files from your project. It deliberately leaves shared registry dependencies (like cn) in place, since other components may still use them, and it does not uninstall npm packages — it reports them instead so you can prune by hand.
flab remove buttonflab rm dialog badgeflab check
alias doctorValidate that the project is set up to use Flab: a valid flab.json, the token layer imported, the CSS file present, and the registry reachable. Warnings do not fail the command; only hard failures (missing or invalid config, an unreachable registry) exit non-zero.
flab checkIt also compares your installed CLI against the version the registry was built with and, if you are behind, prints an upgrade hint. It only hints — see Upgrading the CLI for the actual command.
Global options
| Option | Applies to | Description |
|---|---|---|
--registry <url> | all | Override the registry source for this run, instead of the one in flab.json. |
--overwrite | add | Overwrite existing files. |
--path <alias> | add | Install under a custom ui alias for this invocation. |
--dry-run | add | Show what would change without writing or installing. |
-h, --help | all | Show help. |
-v, --version | all | Show the CLI version. |
Command aliases
| Alias | Canonical command |
|---|---|
upgrade | update |
rm | remove |
doctor | check |
flab.json reference
Written by flab init and read by every other command. It records where the registry lives and how the canonical aliases map to your folders.
{ "$schema": "https://flab-ui.invalid/schema/flab.json", "registry": "https://flab-ui.invalid/r", "css": "app/globals.css", "aliases": { "ui": "@/components/flab", "lib": "@/lib", "hooks": "@/hooks" }, "rsc": true, "iconLibrary": "lucide-react"}| Field | Description |
|---|---|
registry | Base URL (or local path) the CLI fetches registry items from. |
css | Your global stylesheet, where the token import is ensured on init. |
aliases.ui / lib / hooks | Where components, utilities, and hooks land. The canonical @/ui, @/lib, and @/hooks prefixes in registry files are rewritten to these. |
rsc | Whether the project uses React Server Components. Recorded for parity. |
iconLibrary | The icon set components assume. Defaults to lucide-react. |
$schema | Optional JSON Schema URL for editor validation. |
A typical lifecycle
Set up once, pull in what you need, and keep it current over time.
flab init # 1. set the project upflab add button dialog # 2. copy in what you needflab check # 3. confirm config, tokens, and registry are healthy# ...time passes, the registry moves on...flab diff # 4. see what has drifted across the projectflab update dialog # 5. pull the upstream changes into your copyflab remove button # 6. drop a component you no longer use