CLI

Overview

morpha-ui is a thin wrapper around the shadcn CLI that installs Morpha UI components from a gated registry. Components require a one-time browser login; the CLI captures a short-lived token and forwards it to the registry when you run add. If you're not authenticated, add (and init) auto-launch the browser login and then continue the original command — you never have to run login by hand first. init scaffolds a shadcn project and applies the theme; every other command is delegated straight to shadcn.

Installation

No install step — run it with your package manager's runner:

Prerequisites

• A project with shadcn/ui configured (a valid components.json in the project root) — or run npx morpha-ui@latest init to scaffold one and apply the theme in a single step.
• Node.js ≥ 18.
• An approved account (plan: pro).

Getting started

npx morpha-ui@latest init

🚀 Inizializzazione del progetto con shadcn…
✔ Writing components.json.
✔ Installing dependencies.
🎨 Applicazione del tema Morpha…
🔍 Recupero del tema Morpha…
✅ Tema Morpha applicato a app/globals.css.

npx morpha-ui@latest add theme      # write the Morpha tokens into your global CSS
npx morpha-ui@latest add button     # add a component (opens login the first time)

Authentication

You rarely need to run this yourself — add, add theme, and init open the login automatically when a token is missing or expired, then continue the original command. Run login explicitly only to sign in ahead of time or to switch accounts. It uses Clerk with a browser OAuth flow:

npx morpha-ui@latest login

1. The CLI starts a temporary local server on 127.0.0.1:<random-port> and opens /cli/authorize in your browser (the URL is printed as a fallback).
2. You sign in. If your account has pro access, the page redirects back to the local server with a signed token — you never copy/paste anything.
3. The token is saved to ~/.morpha/config.json (permissions 0600).

The token is a JWT that expires after ~30 days. When it expires, add re-opens the login automatically in an interactive terminal (in CI it tells you to run npx morpha-ui@latest login again).

Headless mode (CI)

When no browser is available, supply the token directly:

# paste a token captured from the authorize page
npx morpha-ui@latest login --token <jwt>

# or pass it ambiently to a single command (wins over the stored token)
MORPHA_TOKEN="$MORPHA_TOKEN" npx morpha-ui@latest add button

Commands

npx morpha-ui@latest init                        # new project: shadcn init + theme
npx morpha-ui@latest add button                  # add a component (auto-login if needed)
npx morpha-ui@latest add card --overwrite        # overwrite existing files
npx morpha-ui@latest add theme --primary '#8265bd'  # apply a re-themed palette
npx morpha-ui@latest add theme --merge              # keep your CSS (managed block)
npx morpha-ui@latest whoami                       # check plan / expiry

Aliases: status is the same as whoami, and config clear is the same as logout.

The theme

The Morpha theme is a complete, self-contained stylesheet (@theme inline + :root + .dark + @layer base/utilities). add theme writes it into your global CSS, resolved from components.json → tailwind.css (falling back to app/globals.css, src/app/globals.css, …).

By default it overwrites that file: it keeps your leading @import lines (so @import "tailwindcss" survives) and replaces everything else with the theme — dropping shadcn's default tokens so there are no duplicate/conflicting :root blocks. Re-running is idempotent, and it's safe to re-theme with --primary/--secondary.

• --merge — don't overwrite; instead keep the file and inject the theme inside a managed block (/* === morpha-ui theme start === */ … end === */), replaced in place on re-runs. Use this when your global CSS has other rules you want to keep.
• --dry-run — print the resolved target and what would happen, without writing.

morpha-ui init runs add theme automatically after shadcn init.

Configuration

Two environment variables tune the CLI:

From MORPHA_SITE_URL the CLI derives the registry (${SITE}/r) and the authorize URL (${SITE}/cli/authorize).

The token store at ~/.morpha/config.json (chmod 0600) looks like:

{
  "token": "<jwt>",
  "site": "https://morphaui.com",
  "savedAt": "2026-06-11T10:00:00.000Z",
  "exp": 1752230400
}

The token is never printed — whoami and config only show the decoded plan and exp.

Troubleshooting

In an interactive terminal, 401/403 on add (or init) automatically open the browser login and then retry the command once — the manual fixes below are the fallback for CI/headless contexts (where CI or MORPHA_TOKEN is set, or there's no TTY), which keep failing fast instead of hanging on a browser.