@hex-core/cli
The hex binary — init, add, list, theme set, recipe add.
Install
0.2.3Tool / dlx invocationpnpm dlx @hex-core/cli initWhat it does
`@hex-core/cli` is the `hex` binary. It scaffolds projects, copies components into `src/components/ui/`, swaps theme presets in `globals.css`, and installs multi-component recipes.
It's *not* a runtime dependency. You invoke it via `pnpm dlx @hex-core/cli` (or `npx @hex-core/cli`); nothing sticks to your `package.json`. The CLI bundles the registry data, so it works against fresh installs outside the hex-core monorepo.
For LLM-driven workflows, the equivalent surface is the MCP server (`@hex-core/mcp`). Both speak the same registry — the CLI is invoked by humans; MCP is invoked by agents.
Public API
hex init
pnpm dlx @hex-core/cli initScaffold the Tailwind v4 setup: writes `globals.css` with the default theme's `@theme` block + `:root {}` + `.dark {}`, adds the `@import "@hex-core/components/tailwind.css"` directive, and prints next steps. Idempotent — re-running won't double-write existing tokens.
cd my-next-app
pnpm dlx @hex-core/cli init
# → wrote src/app/globals.css
# → next: pnpm dlx @hex-core/cli add buttonhex add <component...>
pnpm dlx @hex-core/cli add <component...> [--lib]Copy one or more components (and their internal deps) into your project. Component sources land in `src/components/ui/<slug>.tsx`; the `cn` helper and other shared utilities go to `src/lib/utils.ts` unless `--lib` overrides the path. Skips files that already exist so you can run it freely after edits.
pnpm dlx @hex-core/cli add button card input
# → installed button → src/components/ui/button.tsx
# → installed card → src/components/ui/card.tsx
# → installed input → src/components/ui/input.tsxhex list [--category <cat>]
pnpm dlx @hex-core/cli list [--category primitive|component|block|hook]Print every component (or recipe) the bundled registry knows about. Useful when scripting bulk installs.
pnpm dlx @hex-core/cli list --category primitive
# button
# card
# input
# label
# ...hex theme set <name>
pnpm dlx @hex-core/cli theme set <default|midnight|ember|...>Swap the `:root {}` and `.dark {}` blocks in your `globals.css` for the named preset. Recognized names: the three built-ins from `@hex-core/tokens` plus everything in `@hex-core/themes`. Leaves your `@theme {}` block alone.
pnpm dlx @hex-core/cli theme set midnight
# → updated src/app/globals.css :root and .dark blocks for theme "midnight"hex recipe add <name>
pnpm dlx @hex-core/cli recipe add <auth-form|settings-page|...>Install every component a recipe needs in one call, in the order the recipe declares. Resolves to the same six recipes the MCP `list_recipes` tool exposes.
pnpm dlx @hex-core/cli recipe add settings-page
# → installs: tabs, card, input, switch, separator, button
# → next steps: see docs/recipes/settings-pageWorkflows
Bootstrap a new project
Three commands gets you a Next.js + Tailwind v4 app with the design system installed and a Button + Card on the page.
pnpm create next-app@latest my-app --tailwind --app
cd my-app
pnpm dlx @hex-core/cli init
pnpm dlx @hex-core/cli add button cardSwitch your theme without re-running init
Useful when you're A/B-testing a brand. The command rewrites only the token blocks; your custom CSS stays.
pnpm dlx @hex-core/cli theme set ember
# … inspect output …
pnpm dlx @hex-core/cli theme set default # roll backInstall an entire recipe
Recipes are vetted multi-component compositions. The CLI fetches every primitive the recipe needs and prints the post-install checklist.
pnpm dlx @hex-core/cli recipe add auth-form
# → installs: button, input, label, card, separator
# → checklist: wire <form> to your auth handler; see docs/recipes/auth-formCompatibility
- Requires Node.js 20.9+ and a project that already has `package.json`.
- Detects pnpm / npm / yarn / bun automatically when prompting peer-dep installs.
- Bundles the registry into the tarball — works without network access after `pnpm dlx` caches the package.
- Bin name: `hex` (not `hex-cli` or `hexui`).