@foundrykit/cli

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

• Validates that you're in a React-based project (Next.js, Vite, Remix)
• Detects your project structure and suggests smart default paths
• Prompts for custom paths - you can customize where files and folders are created
• Installs required dependencies (if not in a workspace)
• Sets up Tailwind CSS v4 with FoundryKit styles
• Creates component directories in your chosen locations
• Creates utility files (lib/utils.ts or custom path)
• Updates your layout/App file to import FoundryKit styles
• 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:

• Import FoundryKit's pre-configured Tailwind CSS v4 styles
• Set up proper CSS variables for theming
• Configure dark mode support
• 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:

• Detect the workspace configuration
• Skip installing dependencies (they're already linked via workspace)
• 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:

• Ensure your pnpm global bin directory is in your PATH:

  export PATH="$PNPM_HOME:$PATH"
  

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

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

Tailwind CSS v4

If you're migrating from Tailwind CSS v3:

• Remove tailwind.config.js or tailwind.config.ts
• Update your CSS imports to use @import directives
• 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: [e-mail]
• 🐛 Issues: GitHub Issues
• 📖 Docs: https://foundrykit.dev