Skip to content
Velocity X Docs

CLI reference

velocityx

Every command the Velocity Components CLI exposes for installing and theming the library. New to it? Start with Getting started.

velocityx add [components...]

Add one or more components into your project. Omit the slug to browse interactively.

--dest <dir>
Project source root the files are written under (default src)
--force
Overwrite files that already exist
--registry-version <version>
Pin to a specific registry version. The registry only serves "latest" today, so this fails loudly unless it matches.
bash 
$ velocityx add flow-lines expandable-card

Writes real source files, never a package import. Skips any file that already exists unless you pass --force. Records what it wrote in velocityx.lock.json at your project root, so a later --force can tell you when you are about to overwrite edits you made since install. Warns (once, only when it actually wrote files, and only when a tailwind.config.* is present) if your Tailwind config has no `primary` scale.

velocityx list

Every component — free and subscription — grouped by category.

--free
Only the free, MIT-licensed components
--category <name>
Filter by category, e.g. "forms"
bash 
$ velocityx list --category forms

Paid components are listed alongside free ones deliberately — you can see the whole catalogue before paying for it.

velocityx search [query...]

Find a component by name, category or description without scrolling the full list.

--limit <n>
Maximum results to show (default 20)
bash 
$ velocityx search pricing table

Matches name > category > description. Every term in the query must match something (AND, not OR).

velocityx theme

Install the Velocity Tailwind preset + CSS variables. Run once per project.

--dest <dir>
Where to write the theme files (default velocity-theme)
--force
Overwrite an existing theme file — you have probably edited it
bash 
$ velocityx theme

Free and unauthenticated regardless of subscription state — without it, every component renders with no colour.

velocityx login [key]

Save your Velocity Components subscription licence key on this machine.

bash 
$ velocityx login vx_live_xxxxxxxxxxxx

The key is in your receipt email after subscribing. It is verified against the live licence gate before it is saved, so a typo fails here rather than three commands later inside add. Stored at ~/.velocityx/credentials.json, mode 0600 — never in your project.

velocityx logout

Remove the stored licence key from this machine.

bash 
$ velocityx logout

Commands you'll see in --help but shouldn't run

The same binary also carries Aidxn Design's internal client-provisioning tooling — start, init, doctor, content, catalog:sync and every admin:* command. They are not part of the component library, they are not supported, and they all require a ~/.velocityxrc.json holding Supabase, GitHub, Netlify and Anthropic credentials you will never have. They are listed here only because velocityx --help prints them.

One gotcha: running bare velocityx with no sub-command launches start, the internal provisioning wizard — not a help screen. Use velocityx --help or velocityx list instead.