The Wensity CLI.

The Wensity CLI copies component and block source into your project. You run it with your package manager. There is no runtime package to add to dependencies, and no provider to wire up after install.

Registry-aware commands read from the hosted registry. add and update write typed .tsx files into paths defined in wensity.json, rewrite internal imports to your aliases, and install declared package dependencies with your detected package manager. Free components install without login. Pro components and premium blocks require a dashboard API token and an active component license.

This reference covers every command, the config file the CLI expects, global flags, and the errors you are most likely to see in real projects.

Install the CLI

Run the CLI on demand. No global install is required.

$npx wensity@latest --help

Pin an exact version in CI when your team wants reproducible installs, for example pnpm dlx wensity@0.1.5. Use @latest for interactive work on your machine.

Command overview

New to Wensity? Start with Getting started for the browse-to-ship path, or Installation for framework requirements and peer dependencies.

wensity init

Initialise Wensity in a Next.js or Vite project. Writes wensity.json and a small cn() utility.

$npx wensity init

Run this once per repo. The command detects Tailwind config and global CSS paths, sets default aliases for @/components/wensity and @/lib/utils, and installs clsx and tailwind-merge unless you pass --no-install.

Useful flags:

wensity login

Authenticate the CLI with a dashboard API token. The command validates the token against /api/cli/whoami, then stores credentials locally at ~/.config/wensity/credentials.json with 0600 permissions.

$npx wensity login

For CI or scripted setup, pass the token non-interactively:

1pnpm dlx wensity login --token "$WENSITY_TOKEN"

You can also read the token from WENSITY_TOKEN when the flag is omitted. Override the credential file path with WENSITY_CREDENTIALS_FILE if your environment requires it.

After login, Pro component installs use /api/cli/<slug>. Premium block installs use /api/cli/blocks/<slug>. If a token is revoked in the dashboard, the next authenticated request fails immediately.

wensity whoami

Verify the saved token and print the current account and plan.

$npx wensity whoami

Use wensity whoami --json for machine-readable output in setup scripts. The JSON payload includes apiBaseUrl and the resolved credentials path.

wensity list

Print registry entries grouped by access. Components are the default resource type.

$npx wensity list

List premium blocks separately:

$npx wensity list --type block

wensity list --json returns the full registry payload. That is the same shape the website uses for listings and internal tooling.

wensity add

Download a component or block into your project. Components land under src/components/wensity by default. Blocks land under src/components/wensity/blocks.

Install a free component:

$npx wensity add liquid-multimodal-input

Install a premium block after login:

$npx wensity add monolith-hero --type block

How source is resolved:

Free components download from the public registry when no token is saved, or when saved credentials are rejected for a free slug. Pro components require wensity login and download from /api/cli/<slug>. Premium blocks always require login and download from /api/cli/blocks/<slug>.

The CLI rewrites Wensity internal imports to your configured aliases, writes missing helper files in the same pass, and installs declared npm dependencies with your detected package manager unless you pass --no-install.

wensity add refuses to overwrite files that already exist. Pass --dry-run to preview planned writes and dependency installs without touching disk. Pass --force to overwrite during add when you explicitly want that behavior.

wensity update

Re-download a component or block you already added. This command overwrites the local copy so your git diff remains the review surface.

$npx wensity update liquid-multimodal-input

$npx wensity update monolith-hero --type block

Review the resulting diff before committing, especially if your team edits installed files directly.

wensity logout

Remove the saved credential file from your machine.

$npx wensity logout

Global options

These flags work across commands where noted in wensity --help:

wensity.json

Generated by wensity init. Commit this file. It tells the CLI where to write components, where shared utilities live, which Tailwind files to reference, and which registry origin to call.

 1{
 2"$schema": "https://ui.wensity.com/schema/wensity.json",
 3"registry": "https://ui.wensity.com/api/registry",
 4"components": "src/components/wensity",
 5"utils": "src/lib/utils",
 6"tailwind": {
 7  "config": "tailwind.config.ts",
 8  "css": "src/app/globals.css"
 9},
10"aliases": {
11  "components": "@/components/wensity",
12  "utils": "@/lib/utils"
13}
14}

Keep aliases aligned with your TypeScript paths in tsconfig.json. When they match, every CLI-installed file imports correctly on first write.

Custom registry URL

Change the registry field when you mirror the public registry or host internal components behind your own origin. The endpoint must return the same JSON shape as https://ui.wensity.com/api/registry.

Block listings resolve to /api/blocks on the same origin unless you pass --registry explicitly for a list, add, or update command.

Typical workflow

Run wensity init once per project and commit wensity.json. Install free components immediately with wensity add <slug>. Before Pro component or block installs, create a dashboard API token and run wensity login.

Then run wensity add <pro-slug> or wensity add <block-slug> --type block. Import components from @/components/wensity/<slug> and blocks from @/components/wensity/blocks/<slug>, then review the git diff. Use wensity update <slug> when you want a fresh upstream copy.

Troubleshooting

Most failures are authentication, project config, or network related. Start with wensity whoami, then check origin and file conflicts.

Token rotated or revoked

If wensity whoami fails after rotation, log out and authenticate again with a fresh dashboard token.

$pnpm dlx wensity logout
$pnpm dlx wensity login --token "$WENSITY_TOKEN"
$pnpm dlx wensity whoami

Revoked tokens fail immediately because /api/cli/whoami and authenticated source endpoints validate the token hash before returning payload.

Wrong API origin

The CLI reads WENSITY_API_URL, --api-url, or the registry origin embedded in wensity.json. Verify the host when you work behind a proxy or against staging.

$pnpm dlx wensity whoami --api-url https://ui.wensity.com
$WENSITY_API_URL=https://ui.wensity.com pnpm dlx wensity list

File already exists

wensity add stops when a target file already exists. Use wensity update <slug> when you want to replace the local copy with the latest registry source, then review the diff.

Missing dependencies

Run wensity add <slug> --dry-run to see planned files and package dependencies. If you used --no-install, install the printed packages yourself before importing the component.

Error reference

Authenticated endpoints return structured JSON errors. The CLI prints the message and exits with code 1.

1{
2"error": "token_revoked",
3"message": "API token has been revoked. Create a fresh dashboard token and run wensity login again."
4}

Common error codes: