@emara/cli

Copy-paste CLI for Emara UI — a React component library inspired by shadcn/ui, with multi-theme support (5 bases × 17 primaries), warm/dense density, and first-class RTL.

Install

No global install needed:

npx @emara/cli <command>

Quick start

One command — fresh Next.js app pre-wired with Emara UI:

npx @emara/cli create my-app
cd my-app
pnpm dev

create scaffolds Next.js (TypeScript + Tailwind v4 + App Router), installs the Emara peer deps, writes components.json / globals.css (with your chosen theme baked in) / lib/utils.ts, wires the CSS into the root layout, and drops in starter components (Button, Input, Card).

Need a monorepo instead?

npx @emara/cli create my-org                # interactive: pick "Monorepo (Turborepo, 3 apps)"
# or non-interactive:
npx @emara/cli create my-org --architecture monorepo --sharing shared --yes

Scaffolds a pnpm-workspaces + Turborepo monorepo with three apps (apps/web, apps/app, apps/admin) and an Emara-wired shared packages/ui workspace. See Project shapes below.

Existing project:

cd my-existing-app
npx @emara/cli init                  # set up Emara in place
npx @emara/cli add button input card # copy components

Commands

| Command | Purpose | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | create <dir> | Scaffold a new Next.js project pre-wired with Emara UI. Flags: --framework, --architecture <single\|monorepo>, --sharing <shared\|per-app>, --yes, --skip-install, --package-manager. | | init | Set up Emara UI inside an existing project — writes components.json + globals.css + lib/utils.ts, installs peer deps. | | list | List all available components. --installed shows what's already in your project. | | add <names…> | Copy components into aliases.ui. Resolves transitive component dependencies. Installs npm peer deps. Flags: --overwrite, --path, --dry-run, --skip-install. | | update <names…> | Replace local components with the latest registry version. --yes to skip prompts. | | diff [names…] | Unified diff of local vs registry. --exit-on-drift for CI. | | theme show | Print the current theme axes. | | theme set <axis> <value> | Change a theme axis. base/primary/density rewrite globals.css; colorScheme/direction update components.json only. | | theme regenerate | Re-emit globals.css from components.json. | | doctor | Health check the project. --strict exits non-zero on warnings. |

Every command accepts --cwd <dir> to run as if invoked from somewhere else.

Project shapes

create builds one of two shapes:

Single app (default)

my-app/
├── app/                       Next.js App Router
├── components/ui/             starter components copied here
├── lib/utils.ts               cn() helper
├── styles/ (or app/globals.css)
└── components.json            Emara config

Monorepo (pnpm workspaces + Turborepo)

my-org/
├── apps/
│   ├── web/                   marketing / public-facing
│   ├── app/                   authenticated dashboard
│   └── admin/                 internal back-office
├── packages/
│   └── ui/                    only when --sharing shared
├── turbo.json
├── pnpm-workspace.yaml
└── tsconfig.base.json

The 3 apps are scaffolded via create-next-app (skipping their per-app installs — a single root pnpm install hydrates everything in one pass).

--sharing chooses how the apps consume Emara:

| Strategy | Shape | When to pick | | --------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | shared | One packages/ui workspace (@workspace/ui) holds all components. Each app imports from it. | Default — one source of truth; edits propagate; uses Next's transpilePackages. | | per-app | Each app gets its own components/ui/ + lib/utils.ts + theme-baked globals.css. | Apps need to diverge independently — fork-friendly, no cross-app coupling. |

Both modes bake the same theme (chosen at prompt time) into every app. The shared mode writes one components.json at packages/ui/; the per-app mode writes one per app.

Themes

| Axis | Values | Where it lives | | ------------- | ------------------------------------------- | ------------------------------------------------------------ | | base | slate, gray, zinc, stone, neutral | globals.css (bake-time) | | primary | 17 Tailwind hues (red → rose) | globals.css (bake-time) | | density | warm, dense | globals.css (bake-time) | | colorScheme | light, dark, system | components.json default; runtime via <html class="dark"> | | direction | ltr, rtl | components.json default; runtime via <html dir="rtl"> |

License

MIT.