CLI

npx wingo-ui@latest init
npx wingo-ui@latest add button input dialog
npx wingo-ui@latest outdated
npx wingo-ui@latest update

Every command takes these flags:

• --jsonMachine-readable output on stdout, no prompts. Errors come back as { ok: false, error, message, hint }.
• --cwd <dir>Run against another project folder.
• --registry <url>Another Wingo UI server. Defaults to https://wingo-ui.com.
• --verboseLog every request.

Exit codes: 0 done, 1 an error or files left with conflicts, 2 sign in or upgrade needed.

npx wingo-ui@latest init

• Detects Next.js, Vite or React Router, the @/* alias (and adds it to a plain tsconfig.json), your package manager and your Tailwind CSS v4 stylesheet.
• Creates lib/utils.ts with the cn helper and installs clsx and tailwind-merge.
• Merges the design tokens into your stylesheet: only the names you do not have yet, into your existing :root, dark and @theme inline blocks. Your values are never changed.
• Writes wingo-ui.json and offers to set up your coding agent.

• -y, --yesNo prompts.
• --pm <manager>npm, pnpm, yarn or bun, when detection guesses wrong.
• --agents <list>Also run agents install, e.g. --agents claude,cursor or --agents all.
• --no-installPrint the install command instead of running it.
• --dry-runShow what would change.

npx wingo-ui@latest add otp-input
npx wingo-ui@latest add login-page settings-page   # blocks work the same way

It resolves registry dependencies (shared hooks, lib/motion, lib/tones), writes the files, installs npm packages with your package manager, adds any missing tokens and prints the usage example. Imports are rewritten when your project uses another alias such as ~/.

A file that already exists with different content is kept and reported, never overwritten silently. Nothing is written when one of the items fails, for example a Pro item without a Pro account.

• --overwriteReplace existing files that differ.
• --no-installPrint the install command instead of running it.
• --no-cssLeave the stylesheet alone.
• --dry-runShow what would change.

npx wingo-ui@latest search date range picker
npx wingo-ui@latest list --kind block
npx wingo-ui@latest list --access free
npx wingo-ui@latest info otp-input

info prints the description, every prop with its default, the parts, the usage example and what the item brings along.

npx wingo-ui@latest outdated
npx wingo-ui@latest diff button
npx wingo-ui@latest update           # everything
npx wingo-ui@latest update button    # one item

update runs a 3-way merge per file: your file, the version you installed (kept in .wingo-ui/base/) and the new version. Changes on different lines merge cleanly. When you and the update changed the same lines, the file gets conflict markers and the command exits with 1:

<<<<<<< local
  const label = "Save"
=======
  const label = "Save changes"
>>>>>>> wingo-ui 1.2.0

• --theirsSettle conflicts with the new version (also clears markers left from an earlier run).
• --oursSettle conflicts with your version.
• --dry-runShow what would change.
• --forceRe-apply an item even when nothing changed upstream.
• diff --baseCompare with what you installed instead of the latest version.

New dependencies of an updated item are added, files an item no longer ships are reported and kept. See Updates for how versions and releases work.

npx wingo-ui@latest login
npx wingo-ui@latest whoami
npx wingo-ui@latest logout

login shows a code and opens the browser. After you approve it, the CLI creates an API key named after your computer and saves it in ~/.config/wingo-ui/config.json, readable only by you. On a server without a browser, use --no-browser and open the link on any device, or paste a key:

npx wingo-ui@latest login --key wui_...

logout forgets the key on this computer. Revoke it in your account under AI agents.

npx wingo-ui@latest theme apply ./theme.json
npx wingo-ui@latest theme apply https://example.com/theme.json

Applies a theme exported from the theme generator. Unlike init, it replaces the values of the tokens the theme sets. Details in Theming.

npx wingo-ui@latest agents install claude     # codex, gemini, grok, cursor or all
npx wingo-ui@latest agents update
npx wingo-ui@latest agents status

Writes the MCP config and a short rule file for each agent. See Coding agents for what goes where.

• --mcp httpConnect to the remote server with the key from $WINGO_UI_API_KEY (the default when that variable is set).
• --mcp stdioRun the local proxy, which uses the key saved by login (the default otherwise).
• --scope userWrite your user config (~/.codex, ~/.gemini, ~/.cursor) or print the command for it.

npx -y wingo-ui@latest mcp

A stdio MCP server for agents that cannot reach remote servers. It forwards to https://wingo-ui.com/mcp and mirrors its tools when it starts, so new tools appear without a CLI update. Logs go to stderr.

wingo-ui.json records your setup and every installed item with its version, content hash and the hash of each file as written. Commit it, together with .wingo-ui/base/, so teammates can update with merges too.

{
  "$schema": "https://wingo-ui.com/schema/wingo-ui.json",
  "registry": "https://wingo-ui.com",
  "framework": "next",
  "tsx": true,
  "srcDir": false,
  "aliases": {
    "ui": "@/components/ui",
    "blocks": "@/components/blocks",
    "hooks": "@/hooks",
    "lib": "@/lib",
    "utils": "@/lib/utils"
  },
  "css": "app/globals.css",
  "packageManager": "npm",
  "items": {
    "button": {
      "version": "1.0.0",
      "hash": "sha256-adf1989c7690f4cf550c",
      "access": "free",
      "installedAt": "2026-10-01T10:00:00.000Z",
      "files": { "components/ui/button.tsx": { "sha256": "…" } }
    }
  }
}

• WINGO_UI_API_KEYAn API key. Wins over the saved login.
• WINGO_UI_REGISTRYAnother server (WINGO_UI_URL works too).
• WINGO_UI_CONFIG_DIRWhere login saves the key.
• WINGO_UI_NO_UPDATE_CHECKSkip the daily check for a newer CLI.

Use --json for parsing and set the key as a secret. outdated always exits with 0, so a CI step can report updates without failing:

WINGO_UI_API_KEY=${{ secrets.WINGO_UI_API_KEY }} npx wingo-ui@latest outdated --json