@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
• 🎨 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)

# 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:

npx @foundrykit/cli [command]

Quick Start

Initialize FoundryKit in your Next.js project:

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.

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.

foundrykit list [options]

Options:

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

Examples:

# 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.

foundrykit add <component-id> [options]

Options:

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

Examples:

# 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.

foundrykit update <component-id>

Example:

foundrykit update hero-minimal

doctor

Check your project's health and configuration.

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:

@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:

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

Use them like:

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:

   export PATH="$PNPM_HOME:$PATH"

2. Or use the local installation method:

   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 for details.

License

MIT © FoundryKit

Registry

FoundryKit components are served from a live registry hosted at 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:

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: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Docs: https://foundrykit.dev