Installation

Set up a Base UI project, name cilo's two registries and your licence key, add the palette, then add blocks by name. A new project is ready in a few minutes.

Requirements

React 19, Tailwind CSS 4 and shadcn on Base UI, with a components.json whose style starts with base- (base-nova, base-lyra and so on), the shadcn CLI 4.7 or newer and Node.js 20.18.1 or newer. Radix and React Aria projects are not supported: the registry answers them with an error. Step 1 sets up the shadcn project; use a Node.js version supported by your chosen framework.

Set up

Step 1: Create a project

In an empty folder, this makes a Next.js app with shadcn set up on Base UI in the Nova style:

Terminal
npx shadcn@latest init -t next --base base --preset nova --name my-app
cd my-app

For Vite, or another style, name them: init -t vite -b base -p lyra. Already have an app? Run init inside it, without the name. If it has a components.json on Base UI but no theme in its CSS yet, npx shadcn@latest add style --yes writes one. The rest of this page runs in the project's folder.

Step 2: Add the registries

Name both of cilo's registries in components.json, beside the keys already there. @cilo is free and sends nothing; @cilo-pro is the same address with a header that carries your licence key:

components.jsonJSON
{
"registries": {
"@cilo": "https://registry.cilo.com/r/styles/{style}/{name}.json",
"@cilo-pro": {
"url": "https://registry.cilo.com/r/styles/{style}/{name}.json",
"headers": {
"Authorization": "Bearer ${CILO_TOKEN}"
}
}
}
}

Keep {style} as it is: the CLI fills it from the style in the same file. Never put the header on @cilo, or free blocks would ask for the key too. Then put the key in .env.local, where the CLI reads it each time it runs; there is no flag for it. Next.js already keeps .env files out of git.

.env.local
CILO_TOKEN=your-licence-key

Step 3: Add the palette

Once, right after setup, add cilo's default palette. It sets shadcn's colour tokens, light and dark, and leaves the radius to your style:

Terminal
npx shadcn@latest add @cilo/cilo

The other eleven are @cilo/greige, neutral, stone, zinc, mauve, olive, mist, taupe, sand, slate and sage. A project wears one.

Step 4: Add a block

Add a free block as @cilo/<name> and a pro one as @cilo-pro/<name>. Preview first; the dry run lists every file it would write:

Terminal
npx shadcn@latest add @cilo/b-data-table-1 @cilo-pro/pb-order-tracking-1 --dry-run
npx shadcn@latest add @cilo/b-data-table-1 @cilo-pro/pb-order-tracking-1 --yes

The CLI writes each block to components/cilo/<name>.tsx (src/components/cilo/ in a src project), adds the stock shadcn components it is built on in your style, installs the packages it requires (pb-order-tracking-1 brings Leaflet), merges the colours it needs into your CSS, and swaps its icons for your icon library. You can name several items in one command.

Pro pages (pp-…) are not published for now: build a screen from a pro shell, such as pb-sidebar-shells-6, and one block per region.

If the dry run marks one of your existing components/ui files for overwrite, a plain --yes still asks in a terminal; without one, as when an agent runs it, it stops at the question and writes nothing. Save or commit those files first. Use --overwrite only after reviewing every replacement, and restore any shared files you intended to keep. Never overwrite an installed Cilo block just to add a different one; updating a block is the separate step below.

Find blocks

Search the registry by what a block does, and read an item before you add it:

Terminal
npx shadcn@latest search @cilo -q "date range"
npx shadcn@latest search @cilo-pro -q "order tracking" -t block
npx shadcn@latest view @cilo/b-data-table-1

The first finds @cilo/b-date-picker-3. Both namespaces search the same whole catalog, so a search of @cilo also lists pb- items printed with @cilo; add a pb- name as @cilo-pro/<name>. Search matches names, titles and descriptions; view and add also take a block's other names, so @cilo/date-range-picker adds the same block. You can also let your agent search for you through the MCP server.

Use what you added

Import a block from components/cilo, and give it your content the way it takes it:

A data prop
Many pro blocks take their content as one typed data prop and export its type. Build your data against it and leave the block's file as installed.
Top constants
Other blocks hold their content in constants at the top of the file, such as b-data-table-1's PAYMENTS and COLUMN_LABELS. Replace those with yours.
app/orders/[id]/page.tsx
import { DeliveryTracking, type DeliveryTrackingData } from "@/components/cilo/pb-order-tracking-1"
import { PaymentsDataTable } from "@/components/cilo/b-data-table-1"

Change a block in shadcn's order: its props first, then className, then the smallest edit to its source, then a wrapper of your own. Never paste a block into a page; install it and import it.

Update a block

A block in your project is your copy, so a new version never lands on its own. See what would change, file by file, then take it:

Terminal
npx shadcn@latest add @cilo/b-data-table-1 --diff b-data-table-1.tsx
npx shadcn@latest add @cilo-pro/pb-order-tracking-1 --diff pb-order-tracking-1.tsx
npx shadcn@latest add @cilo/b-data-table-1 --yes --overwrite

Overwriting replaces your edits to those files, so commit before you run it and bring your changes back from the diff.

Add the agent skill

Install Cilo’s instructions for your coding agent after configuring the free registry:

Terminal
npx shadcn@latest add @cilo/skill

The skill explains how to find, install and adapt blocks. MCP is optional for this workflow.

Troubleshooting

“Registry "@cilo-pro" requires the following environment variables:”
The CLI found no key. Put it in .env.local in the project's folder, the one you run the command from, as CILO_TOKEN.
“You are not authorized to access the item … [license_required] License required for this item.”
One error: the CLI's headline for the registry's 401, with the registry's own words under it. The registry got a pro item without a key it accepts. Check the line in .env.local (the key exactly as you were given it), and that the item is added as @cilo-pro/<name>: a pb- name under @cilo is refused the same way.
“Unknown registry "@cilo".”
components.json has no registries entry by that name. Add both, as step 2 shows, in the components.json of the folder you run the CLI from.
“Cilo has blocks for Base UI projects only”
Your components.json style is a Radix or React Aria one (new-york, radix-…, aria-…). cilo needs a base- style; start a Base UI project with init -b base.
“Unknown style "comet". Valid styles: nova, lyra, luma, maia, mira, rhea, sera, vega.”
The style in components.json, after base-, is not one of the eight, or {style} in the registry URL was replaced by hand. Keep it literal; the CLI fills it.
“The item at <url> was not found … [item_not_found] Item "b-chart-99" not found.”
One error: the CLI's headline with the registry's own words under it. No item has that name. Search for it, or check the family and the number; a pro name needs the pro namespace.

A run with --yes that wrote nothing stopped at an overwrite question; see step 4. A few type errors come from stock shadcn, not cilo, and shadcn tracks them:

  • If a sidebar cannot find use-mobile after installation, check the hook location against the hooks alias in your components.json.
  • Vite's strict tsc flags an unused React import in the stock scroll-area.
  • The stock spinner passes svg props to hugeicons and remixicon icons.
  • Phosphor icons cannot load in a Server Component; cilo's blocks that draw icons start with "use client" for this.