npm package: @foundrykit/cli
Description: The official CLI for FoundryKit - a modern component library for Next.js applications with Tailwind CSS v4 support.
Latest version: 1.0.16

# @foundrykit/cli

The official CLI for FoundryKit - a modern component library for Next.js
applications with Tailwind CSS v4 support.

## Features

- 🌐 **Live Registry** - Fetches components from the hosted registry at
  [foundry.umiflow.com](https://foundry.umiflow.com)
- 🎨 **Interactive Selection** - Multi-select components with keyboard
  navigation
- 📦 **Smart Dependencies** - Automatically installs required component
  dependencies
- 🎯 **Tailwind CSS v4** - Full support for the latest Tailwind CSS version
- 🔄 **Auto-updates** - Registry automatically updates when new components are
  released

## Installation

### Global Installation (Recommended)

```bash
# Using pnpm (recommended)
pnpm add -g @foundrykit/cli

# Using npm
npm install -g @foundrykit/cli

# Using yarn
yarn global add @foundrykit/cli
```

### Local Installation

You can also use the CLI without installing it globally:

```bash
npx @foundrykit/cli [command]
```

## Quick Start

Initialize FoundryKit in your Next.js project:

```bash
foundrykit init
```

This will:

- ✅ Detect your Next.js project
- ✅ Install required FoundryKit dependencies
- ✅ Set up Tailwind CSS v4 configuration
- ✅ Create necessary directories and files
- ✅ Add helper scripts to your package.json

## Commands

### `init`

Initialize FoundryKit in your Next.js project.

```bash
foundrykit init [options]
```

**Options:**

- `-f, --force` - Overwrite existing files
- `--skip-install` - Skip installing dependencies
- `--skip-prompts` - Use default paths without prompting for customization

**What it does:**

1. Validates that you're in a React-based project (Next.js, Vite, Remix)
2. **Detects your project structure** and suggests smart default paths
3. **Prompts for custom paths** - you can customize where files and folders are
   created
4. Installs required dependencies (if not in a workspace)
5. Sets up Tailwind CSS v4 with FoundryKit styles
6. Creates component directories in your chosen locations
7. Creates utility files (`lib/utils.ts` or custom path)
8. Updates your layout/App file to import FoundryKit styles
9. Adds convenient scripts to package.json

**Path Customization:** The init command now intelligently detects your project
structure and offers to customize paths:

- Automatically detects if you use `src/` directory
- Finds existing `components/`, `lib/`, `styles/` directories
- Suggests appropriate defaults based on your framework (Next.js, Vite, Remix)
- Allows you to customize each path individually

Example prompts:

```
📂 Configure installation paths:
Press enter to use the default value shown in parentheses

? Utils file path: (./src/lib/utils.ts)
? Components directory: (./src/components/components)
? Primitives directory: (./src/components/primitives)
? Blocks directory: (./src/components/blocks)
? Hooks directory: (./src/hooks)
? Animations directory: (./src/components/animations)
? Global styles file: (./src/app/globals.css)
? Lib directory: (./src/lib)
```

### `list`

List all available FoundryKit components and blocks from the live registry.

```bash
foundrykit list [options]
```

**Options:**

- `-c, --category <category>` - Filter by category (primitives, components,
  blocks)
- `-s, --search <term>` - Search components by name or description

**Examples:**

```bash
# List all components
foundrykit list

# List only blocks
foundrykit list -c blocks

# Search for button components
foundrykit list -s button

# Components are fetched from https://foundry.umiflow.com/registry
```

### `add`

Add a component or block to your project. Components are fetched from the live
registry at [foundry.umiflow.com](https://foundry.umiflow.com).

```bash
foundrykit add <component-id> [options]
```

**Options:**

- `-o, --overwrite` - Overwrite existing files
- `-p, --path <path>` - Custom installation path

**Examples:**

```bash
# Interactive mode - select from a list of all components
foundrykit add

# Add a specific component from the registry
foundrykit add hero-minimal

# Add a button component to a custom path
foundrykit add button -p components/custom

# Overwrite existing component
foundrykit add card -o
```

### `update`

Update an existing component or block to the latest version.

```bash
foundrykit update <component-id>
```

**Example:**

```bash
foundrykit update hero-minimal
```

### `doctor`

Check your project's health and configuration.

```bash
foundrykit doctor
```

This command checks:

- Next.js installation
- FoundryKit dependencies
- Tailwind CSS v4 configuration
- Project structure
- Common issues and fixes

## Tailwind CSS v4 Support

FoundryKit CLI is built for Tailwind CSS v4, which uses CSS-based configuration
instead of JavaScript config files. The CLI will:

1. Import FoundryKit's pre-configured Tailwind CSS v4 styles
2. Set up proper CSS variables for theming
3. Configure dark mode support
4. Include all necessary Tailwind directives

Your `globals.css` will be updated to include:

```css
@import '@foundrykit/tailwind/globals.css';
```

This provides:

- Complete Tailwind CSS v4 setup
- CSS variables for colors and theming
- Dark mode configuration
- Component-specific styles
- Proper content scanning for all FoundryKit packages

## Working in a Monorepo

If you're using FoundryKit in a monorepo with workspace packages (like pnpm
workspaces), the CLI will:

1. Detect the workspace configuration
2. Skip installing dependencies (they're already linked via workspace)
3. Use the local workspace packages instead of npm registry

## Package.json Scripts

After initialization, you'll have these convenient scripts:

```json
{
  "scripts": {
    "foundrykit": "foundrykit",
    "fk": "foundrykit"
  }
}
```

Use them like:

```bash
npm run fk list
pnpm fk add hero-minimal
yarn fk doctor
```

## Project Structure

After initialization, your project will have:

```
your-nextjs-app/
├── app/
│   ├── layout.tsx       # Updated with FoundryKit imports
│   └── globals.css      # Tailwind CSS v4 with FoundryKit styles
├── components/
│   ├── ui/             # UI components
│   ├── blocks/         # Page blocks
│   └── providers.tsx   # Theme provider setup
├── lib/
│   └── utils.ts        # Utility functions (cn, etc.)
└── hooks/              # Custom React hooks
```

## Requirements

- Node.js 18.0.0 or higher
- React 18 or 19
- One of the following frameworks:
  - Next.js 14.0.0 or higher
  - Vite 5.0.0 or higher
  - Remix 2.0.0 or higher
- Tailwind CSS v4

## Troubleshooting

### Command not found

If you get `command not found: foundrykit` after global installation with pnpm:

1. Ensure your pnpm global bin directory is in your PATH:

   ```bash
   export PATH="$PNPM_HOME:$PATH"
   ```

2. Or use the local installation method:
   ```bash
   npx @foundrykit/cli [command]
   ```

### Workspace Detection

If you're in a monorepo and the CLI tries to install packages from npm:

1. Ensure your `pnpm-workspace.yaml` is properly configured
2. Check that workspace packages use `workspace:*` protocol
3. Use `--skip-install` flag and link packages manually if needed

### Tailwind CSS v4

If you're migrating from Tailwind CSS v3:

1. Remove `tailwind.config.js` or `tailwind.config.ts`
2. Update your CSS imports to use `@import` directives
3. Run `foundrykit init --force` to set up v4 configuration

## Contributing

Contributions are welcome! Please see our
[Contributing Guide](../../CONTRIBUTING.md) for details.

## License

MIT © FoundryKit

## Registry

FoundryKit components are served from a live registry hosted at
[foundry.umiflow.com](https://foundry.umiflow.com). The registry automatically
updates when new components are released on GitHub.

### Registry Endpoints

- **Component List**: `https://foundry.umiflow.com/registry` - Returns all
  component metadata
- **Individual Component**: `https://foundry.umiflow.com/registry/[id]` -
  Returns full component data including files
- **Filtered List**:
  `https://foundry.umiflow.com/registry?category=primitives&search=button` -
  Supports filtering

### Custom Registry

To use a custom registry, set the environment variable:

```bash
export FOUNDRYKIT_REGISTRY_URL=https://your-registry.com
foundrykit list
```

### Offline Mode

If the registry is unavailable, the CLI will automatically fall back to a local
component cache, ensuring you can always work offline.

## Support

- 📧 Email: support@foundrykit.dev
- 🐛 Issues: [GitHub Issues](https://github.com/foundrykit/foundrykit/issues)
- 📖 Docs: [https://foundrykit.dev](https://foundrykit.dev)