Morpha UI CLI

A thin wrapper around the shadcn CLI that installs Morpha UI components from a gated registry. Components require a one-time browser login (Clerk OAuth) — the CLI captures a short-lived token and forwards it to the registry as you run add. When you're not authenticated, add (and init) auto-launch the login and then continue the command.

v2 — breaking change. The old email + secretKey flow is gone. Authentication is now morpha-ui login (browser OAuth). See Migrating from v1.

🚀 Quick start

# New project: scaffold shadcn + apply the theme + install the skill (auto-opens login)
npx morpha-ui@latest init

# Add components (auto-opens login the first time)
npx morpha-ui@latest add button
npx morpha-ui@latest add card

Works with any package runner:

npx morpha-ui@latest add button           # npm
pnpm dlx morpha-ui@latest add button       # pnpm
bunx --bun morpha-ui@latest add button     # bun

Prerequisites

• A project with shadcn/ui configured (a valid components.json in the project root) — or run morpha-ui init to scaffold one and apply the theme in a single step.
• Node.js ≥ 18 (the CLI uses the global fetch, crypto, and base64url).
• An approved Morpha UI account (plan: pro).

🔐 Authentication

Morpha UI uses browser-based OAuth through Clerk.

morpha-ui login

What happens:

1. The CLI starts a temporary local server on 127.0.0.1:<random-port> and opens https://morphaui.com/cli/authorize in your browser (the URL is also printed, in case the browser does not open).
2. You sign in with Clerk. If your account has pro access, the page redirects back to the local server with a signed token.
3. The token is saved to ~/.morpha/config.json (permissions 0600) and the browser tab can be closed.

The token is a JWT that expires after ~30 days. When it expires, add tells you to run morpha-ui login again.

Pro access is granted by the Morpha UI owner. A logged-in account without pro access sees an upgrade prompt and no token is issued.

Headless / manual login

If you can't open a browser (CI, remote shell), paste a token directly:

morpha-ui login --token <jwt>

You can copy the token from the authorize page (it shows a copyable token box when opened manually) and paste it here.

Logging out

morpha-ui logout         # removes ~/.morpha/config.json (and the legacy v1 file)
morpha-ui config clear   # alias of logout

🔧 Commands

| Command | Description | | --- | --- | | morpha-ui init [args…] | Scaffold a shadcn project (shadcn init), merge the Morpha theme into your global CSS, then install the Morpha UI agent skill. | | morpha-ui login | Authenticate via browser (Clerk OAuth). | | morpha-ui login --token <jwt> | Authenticate headless with a pasted token. | | morpha-ui logout | Remove the stored token. | | morpha-ui add <name> [args…] | Add a component; auto-launches login if needed. Extra args (--overwrite, --diff, …) pass through to shadcn. | | morpha-ui add theme [--primary #hex] [--secondary #hex] [--merge] [--dry-run] | Write the Cupido theme into your global CSS (from components.json → tailwind.css). Overwrites by default (keeping @import lines); --merge injects a managed block instead. | | morpha-ui add skills [--path <file>] [--dry-run] | Install the Morpha UI agent skill — a markdown file teaching an agent the components, tokens and foundations. Free, no login. Writes to .claude/skills/morpha-ui/SKILL.md by default; --path overrides. | | morpha-ui list | List all components. | | morpha-ui whoami | Show the current plan and token expiry (never prints the token). | | morpha-ui config | Show the site, store path, and auth status. | | morpha-ui <other> | Any other command is delegated to shadcn@latest. |

Examples

morpha-ui init                       # new project: shadcn init + theme
morpha-ui add button                 # add a component (auto-login if needed)
morpha-ui add card --overwrite       # overwrite existing files
morpha-ui add theme --primary '#8265bd'  # apply a re-themed palette (overwrite)
morpha-ui add theme --merge          # keep your CSS; theme goes in a managed block
morpha-ui add theme --dry-run        # preview the target file without writing
morpha-ui add skills                 # install the agent skill (free, no login)
morpha-ui add skills --path AGENTS.md  # write the skill to a custom path
morpha-ui list                       # see what's available
morpha-ui whoami                     # check your plan / expiry

🛠️ Advanced usage / CI

Two environment variables tune the CLI:

| Variable | Purpose | Default | | --- | --- | --- | | MORPHA_TOKEN | Ambient token for add (wins over the stored token). Useful in CI. | — | | MORPHA_SITE_URL | Override the base URL the CLI talks to. | https://morphaui.com |

# CI: install a pro component without an interactive login
MORPHA_TOKEN="$MORPHA_TOKEN" npx morpha-ui@latest add button

# Point the CLI at a local dev server
MORPHA_SITE_URL=http://localhost:3000 morpha-ui list

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

Configuration file

The token is stored in ~/.morpha/config.json (chmod 0600):

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

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

🔍 Troubleshooting

In an interactive terminal these auth failures auto-open the browser login and retry the command once; the fixes below apply in CI/headless (where CI or MORPHA_TOKEN is set, or there's no TTY), which fail fast instead.

| Symptom | Meaning | Fix | | --- | --- | --- | | 💎 "<name>" è un componente pro | No token, and the component is pro. | morpha-ui login (or set MORPHA_TOKEN). | | 🔒 Autenticazione richiesta (401) | Registry got no token. | morpha-ui login. | | 🚫 Token non valido/scaduto o account non-pro (403) | Token expired/invalid, or the account isn't pro. | morpha-ui login (re-auth or request pro access). | | ❓ "<name>" non trovato (404) | Unknown component name. | morpha-ui list. | | ⏱️ Token scaduto | Local token past its expiry. | morpha-ui login. |

🔄 Migrating from v1

v1 used morpha-ui auth with an email + secret key stored in ~/.morpha-ui-config.json. That flow has been removed.

• Run morpha-ui login instead of morpha-ui auth.
• The old ~/.morpha-ui-config.json is deprecated; logout / config clear remove it automatically.
• No secretKey or email is used or stored anymore.

morpha-ui remains a drop-in shadcn wrapper — any non-Morpha command (diff, build, …) is delegated to shadcn@latest. (init is now a Morpha command: it runs shadcn init, applies the theme, then installs the agent skill.)

🔗 Links

• Documentation: morphaui.com/docs/ui-kit/cli
• Website: morphaui.com
• GitHub: github.com/c4sto/morpha-ui