npm package: @microbuild/cli
Description: CLI tool for adding Microbuild components to your project - like shadcn/ui
Author: Microbuild
Latest version: 0.2.0

# @microbuild/cli

A CLI for adding Microbuild components to your project.

[![npm version](https://img.shields.io/npm/v/@microbuild/cli)](https://www.npmjs.com/package/@microbuild/cli)

## Usage

Use the `init` command to set up a new project and the `add` command to add components.

```bash
npx @microbuild/cli init
npx @microbuild/cli add input select-dropdown
```

## init

Use the `init` command to initialize configuration and dependencies for a new project.

The `init` command creates a `microbuild.json` file, sets up directory structure, and checks for required dependencies.

```bash
npx @microbuild/cli init
```

### Options

```
Usage: microbuild init [options]

initialize your project and install dependencies

Options:
  -y, --yes       skip confirmation prompt (default: false)
  -c, --cwd <cwd> the working directory (defaults to current directory)
  -h, --help      display help for command
```

## add

Use the `add` command to add components to your project.

```bash
npx @microbuild/cli add [component]
```

### Options

```
Usage: microbuild add [options] [components...]

add components to your project

Arguments:
  components         name of components to add

Options:
  -a, --all          add all available components (default: false)
  --with-api         also add API routes and Supabase auth templates
  --category <name>  add all components from a category
  -o, --overwrite    overwrite existing files (default: false)
  -n, --dry-run      preview changes without modifying files
  --cwd <cwd>        the working directory (defaults to current directory)
  -h, --help         display help for command
```

### Examples

```bash
# Add specific components
npx @microbuild/cli add input
npx @microbuild/cli add input select-dropdown datetime

# Add collection-form (includes VForm + all 32 interface components)
npx @microbuild/cli add collection-form

# Add all components from a category
npx @microbuild/cli add --category selection

# Add all components
npx @microbuild/cli add --all
```

## list

Use the `list` command to view all available components.

```bash
npx @microbuild/cli list
```

### Options

```
Usage: microbuild list [options]

list available components

Options:
  --category <name>  filter by category
  --json             output as JSON
  -h, --help         display help for command
```

## bootstrap

Use the `bootstrap` command for full project setup in a single non-interactive command. Recommended for AI agents and CI/CD pipelines.

```bash
npx @microbuild/cli bootstrap
```

### Options

```
Usage: microbuild bootstrap [options]

Full project setup: init + add --all + install deps + validate (single command for AI agents)

Options:
  --cwd <cwd>          the working directory (defaults to current directory)
  --skip-deps          skip npm dependency installation
  --skip-validate      skip post-install validation
  -h, --help           display help for command
```

### What Bootstrap Does

1. Creates `microbuild.json` and project skeleton (package.json, tsconfig, Next.js layout/page, design tokens)
2. Copies all 40+ UI components to `components/ui/`
3. Copies types, services, hooks to `lib/microbuild/`
4. Copies API proxy routes (fields, items, relations, files)
5. Copies auth proxy routes (login, logout, user, callback) + login page
6. Copies Supabase auth utilities and middleware
7. Runs `pnpm install` to resolve all dependencies
8. Validates the installation

**Auth Routes Installed:**
| Route | Method | Purpose |
|-------|--------|---------|
| `/api/auth/login` | POST | Login via Supabase Auth (server-side, no CORS) |
| `/api/auth/logout` | POST | Sign out and clear session cookies |
| `/api/auth/user` | GET | Get current user profile |
| `/api/auth/callback` | GET | Handle OAuth/email-confirm redirects |
| `/app/login/page.tsx` | — | Login page using proxy pattern |

## validate

Use the `validate` command to check your Microbuild installation for common issues.

```bash
npx @microbuild/cli validate
```

### Options

```
Usage: microbuild validate [options]

validate Microbuild installation (check imports, missing files, SSR issues)

Options:
  --json           output as JSON for CI/CD
  --cwd <cwd>      the working directory (defaults to current directory)
  -h, --help       display help for command
```

### What It Checks

- **Untransformed imports** - `@microbuild/*` imports that weren't converted to local paths
- **Missing lib files** - Required utility modules not present (types, services, hooks, utils)
- **Missing CSS files** - CSS required by rich text editors (RichTextHTML.css, InputBlockEditor.css)
- **SSR issues** - Components like InputBlockEditor exported without SSR-safe wrappers
- **Missing API routes** - DaaS integration routes for fields, items, permissions

### Example Output

```
✗ Found 2 error(s):

  ✗ src/components/ui/input.tsx:5
    Untransformed import: import { Field } from '@microbuild/types';

  ✗ lib/microbuild/interface-registry.ts
    Missing required file for utils module

⚠ Found 1 warning(s):

  ⚠ components/ui/index.ts
    InputBlockEditor exported directly may cause SSR errors. Use input-block-editor-wrapper instead.

💡 Suggestions:

  1. Fix 2 untransformed import(s) by running: pnpm cli add --all --overwrite --cwd .
  2. Update components/ui/index.ts to export InputBlockEditor from './input-block-editor-wrapper'
```

## diff

Use the `diff` command to preview changes before adding a component.

```bash
npx @microbuild/cli diff [component]
```

### Options

```
Usage: microbuild diff [options] <component>

preview changes before adding a component

Options:
  --cwd <cwd>      the working directory (defaults to current directory)
  -h, --help       display help for command
```

## status

Use the `status` command to view all installed Microbuild components and their origins.

```bash
npx @microbuild/cli status
```

### Options

```
Usage: microbuild status [options]

show installed Microbuild components and their origins

Options:
  --json           output as JSON
  --cwd <cwd>      the working directory (defaults to current directory)
  -h, --help       display help for command
```

### Example Output

```
📦 Microbuild Status

Config file: microbuild.json
Lib modules: types, hooks, services
Components:  input, select-dropdown, list-m2m

Installed Files:

  @microbuild/ui-interfaces/input
    └─ src/components/ui/input.tsx
       v1.0.0 (2026-01-12)

  @microbuild/lib/hooks
    └─ src/lib/microbuild/hooks/useRelationM2M.ts
       v1.0.0 (2026-01-12)

Total: 15 files from Microbuild
```

## microbuild.json

The `microbuild.json` file holds configuration for your project. We use it to understand how your project is set up and how to generate components customized for your project.

You can create a `microbuild.json` file by running the `init` command.

```json
{
  "$schema": "https://microbuild.dev/schema.json",
  "model": "copy-own",
  "tsx": true,
  "srcDir": true,
  "aliases": {
    "components": "@/components/ui",
    "lib": "@/lib/microbuild"
  },
  "installedLib": [],
  "installedComponents": []
}
```

### tsx

Choose between TypeScript or JavaScript components.

Setting this option to `false` allows components to be added as JavaScript with the `.jsx` file extension.

```json
{
  "tsx": true | false
}
```

### srcDir

Whether your project uses the `src/` directory structure.

```json
{
  "srcDir": true | false
}
```

### aliases

The CLI uses these values to place generated components in the correct location.

```json
{
  "aliases": {
    "components": "@/components/ui",
    "lib": "@/lib/microbuild"
  }
}
```

Path aliases have to be set up in your `tsconfig.json` or `jsconfig.json` file:

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

### installedLib and installedComponents

These arrays track what has been installed. The CLI uses them to avoid reinstalling dependencies.

## What Gets Copied

When you add a component, the CLI:

1. **Copies the component source** to your components directory
2. **Copies required lib modules** (types, services, hooks) if needed
3. **Transforms imports** from `@microbuild/*` to local paths
4. **Reports missing dependencies** that need to be installed

### Example: Adding `list-m2m`

```bash
npx @microbuild/cli add list-m2m
```

This copies:
- `components/ui/list-m2m.tsx` - The component
- `lib/microbuild/types/` - Type definitions
- `lib/microbuild/services/` - CRUD services
- `lib/microbuild/hooks/` - React hooks

### Import Transformation

Original (in source):
```tsx
import { useRelationM2M } from '@microbuild/hooks';
import type { M2MItem } from '@microbuild/types';
```

Transformed (in your project):
```tsx
import { useRelationM2M } from '@/lib/microbuild/hooks';
import type { M2MItem } from '@/lib/microbuild/types';
```

## Component Categories

| Category | Components |
|----------|------------|
| `input` | Input, Textarea, InputCode, InputBlockEditor, Tags |
| `selection` | SelectDropdown, SelectRadio, SelectMultipleCheckbox, SelectIcon, AutocompleteAPI, CollectionItemDropdown |
| `datetime` | DateTime |
| `boolean` | Boolean, Toggle |
| `media` | FileInterface, FileImage, Files, Upload, Color |
| `relational` | ListM2M, ListM2O, ListO2M, ListM2A |
| `layout` | Divider, Notice, GroupDetail, Slider |
| `rich-text` | RichTextHtml, RichTextMarkdown |
| `collection` | VForm, CollectionForm, CollectionList |

### VForm and CollectionForm

When you add `collection-form`, it automatically includes:
- **VForm** - Dynamic form component that renders any field type
- **32 interface components** - All field types (input, select, datetime, M2M, M2O, etc.)
- **Lib modules** - types, services, hooks, and field-interface-mapper utilities

This is because `collection-form` has `registryDependencies: ["vform"]` and VForm has dependencies on all interface components.

## Peer Dependencies

Components require these external packages:

**Core (always needed):**
```bash
pnpm add @mantine/core @mantine/hooks react react-dom
```

**Component-specific:**
```bash
# DateTime component
pnpm add @mantine/dates dayjs

# Icon components
pnpm add @tabler/icons-react

# File upload
pnpm add @mantine/dropzone

# CollectionForm notifications
pnpm add @mantine/notifications

# Rich text editor
pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-link
```

**Utils (optional, for cn() helper):**
```bash
pnpm add clsx tailwind-merge
```

## Project Structure After Installation

```
your-project/
├── app/
│   ├── api/
│   │   ├── auth/                        # Auth proxy routes
│   │   │   ├── login/route.ts           # POST - Supabase login
│   │   │   ├── logout/route.ts          # POST - Sign out
│   │   │   ├── user/route.ts            # GET - Current user info
│   │   │   └── callback/route.ts        # GET - OAuth callback
│   │   ├── fields/[collection]/route.ts # Fields proxy
│   │   ├── items/[collection]/route.ts  # Items proxy
│   │   └── ...
│   └── login/page.tsx                   # Login page template
├── src/
│   ├── components/
│   │   └── ui/
│   │       ├── input.tsx
│   │       ├── select-dropdown.tsx
│   │       └── datetime.tsx
│   └── lib/
│       ├── microbuild/
│       │   ├── utils.ts
│       │   ├── types/
│       │   │   ├── index.ts
│       │   │   ├── core.ts
│       │   │   ├── file.ts
│       │   │   └── relations.ts
│       │   ├── services/
│       │   │   ├── index.ts
│       │   │   ├── api-request.ts
│       │   │   ├── items.ts
│       │   │   ├── fields.ts
│       │   │   └── collections.ts
│       │   └── hooks/
│       │       ├── index.ts
│       │       ├── useRelationM2M.ts
│       │       ├── useRelationM2O.ts
│       │       └── ...
│       ├── api/auth-headers.ts          # Auth header utilities
│       └── supabase/                    # Supabase client utilities
│           ├── server.ts
│           └── client.ts
├── middleware.ts                         # Auth middleware
├── microbuild.json
└── package.json
```

## CLI Commands Reference

```bash
# Initialize project
microbuild init [--yes] [--cwd <path>]

# Bootstrap full project (init + add all + deps + validate)
microbuild bootstrap [--cwd <path>] [--skip-deps] [--skip-validate]

# Add components
microbuild add [components...] [--all] [--category <name>] [--overwrite] [--cwd <path>]

# List components
microbuild list [--category <name>] [--json]

# Preview changes
microbuild diff <component> [--cwd <path>]

# Validate installation
microbuild validate [--json] [--cwd <path>]

# Check installed components
microbuild status [--json] [--cwd <path>]

# Component info and dependency tree
microbuild info <component> [--json]
microbuild tree <component> [--json] [--depth <n>]

# Auto-fix common issues
microbuild fix [--dry-run] [--yes] [--cwd <path>]

# Check for component updates
microbuild outdated [--json] [--cwd <path>]
```

## Troubleshooting

### "Registry file not found"

Make sure you're running the CLI from within the Microbuild workspace or have the registry properly configured.

### "microbuild.json not found"

Run `npx @microbuild/cli init` first to initialize your project.

### Import errors after adding components

Ensure your `tsconfig.json` has the correct path aliases:

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

## Development

Build the CLI:

```bash
cd packages/cli
pnpm build
```

Run in development:

```bash
pnpm dev
```

Test locally:

```bash
node dist/index.js init
node dist/index.js add input
```

## License

MIT