Morpha UI CLI

A thin wrapper around the shadcn CLI that installs Morpha UI components from a gated registry. Free components install with no auth; pro 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.

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

🚀 Quick start

# 1. Authenticate once (opens your browser)
npx morpha-ui@latest login

# 2. Add components
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).
• Node.js ≥ 18 (the CLI uses the global fetch, crypto, and base64url).
• For pro components: 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 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. Extra args (--dry-run, --overwrite, --diff, …) pass through to shadcn. | | morpha-ui list | List all free and pro 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 add button                 # add a component
morpha-ui add card --overwrite       # overwrite existing files
morpha-ui add theme --dry-run        # preview without writing
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

| 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 (init, diff, …) is delegated to shadcn@latest.

🔗 Links

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