CLI

Introduction

The polkadot-ui CLI is a command line interface for adding Polkadot UI components to your project with automatic API setup and configuration.

Quick Start

The fastest way to get started is to add a component to your project:

npx polkadot-ui@latest add <component-name>

Installation

You can use the CLI without installation using npx, pnpm dlx, or bunx:

# Using npx
npx polkadot-ui@latest

# Using pnpm
pnpm dlx polkadot-ui@latest

# Using bun
bunx polkadot-ui@latest

Global Options

All commands support these global options:

Commands

add

Add a component to your project.

polkadot-ui add <component> [options]

Arguments:

• <component> - Component name to install

Description: Adds a Polkadot UI component to your project. If no project is found, it will offer to create one. Automatically sets up shadcn/ui if not already initialized.

Examples:

# Add a component interactively
polkadot-ui add block-number

# Add a component with no prompts
polkadot-ui add block-number --yes

# Add from development registry
polkadot-ui add block-number --dev

# Force overwrite existing files
polkadot-ui add block-number --force

# Verbose output
polkadot-ui add block-number --verbose

What it does:

1. Validates project setup (package.json, React, framework)
2. Creates new project if none exists (when prompted)
3. Initializes shadcn/ui if not already set up
4. Fetches component from registry
5. Installs component with shadcn CLI
6. Sets up Polkadot API if required by component
7. Generates chain metadata and types

init

Initialize a new project with Polkadot UI components.

polkadot-ui init [options]

Description: Creates a new project with your choice of Next.js or Vite, automatically configures TypeScript, ESLint, Tailwind CSS, and initializes shadcn/ui.

Examples:

# Interactive setup
polkadot-ui init

# Skip all prompts and use defaults (Next.js)
polkadot-ui init --yes

# Use development registry
polkadot-ui init --dev

# Verbose output
polkadot-ui init --verbose

Default Configuration (with --yes):

• Framework: Next.js
• TypeScript: Enabled
• ESLint: Enabled
• Tailwind CSS: Enabled
• App Router: Enabled
• Src Directory: Disabled
• Turbopack: Disabled
• Import Alias: @/*
• Polkadot Library: papi
• Base Color: neutral
• CSS Variables: Enabled

list

List available components from the registry.

polkadot-ui list [options]

Description: Shows all available components in the registry with their descriptions and requirements.

Examples:

# List all components
polkadot-ui list

# List from development registry
polkadot-ui list --dev

# Verbose output with detailed information
polkadot-ui list --verbose

Output includes:

• Component name
• Description
• Whether it requires Polkadot API
• Dependencies
• Registry dependencies (other components)

help

Show help information.

polkadot-ui help [command]

Examples:

# Show general help
polkadot-ui help

# Show help for specific command
polkadot-ui help add
polkadot-ui help init
polkadot-ui help list

Usage Examples

Quick Start

Create a new project and add a component:

# Create new project with defaults
mkdir my-polkadot-app
cd my-polkadot-app
polkadot-ui init --yes

# Add a component
polkadot-ui add block-number --yes

Development Workflow

Working with local registry during development:

# List components from local registry
polkadot-ui list --dev

# Add component from local registry
polkadot-ui add block-number --dev --yes

Existing Project

Add components to an existing React project:

# The CLI will detect your existing setup
polkadot-ui add block-number

# Force overwrite if you need to update files
polkadot-ui add block-number --force

Project Requirements

The CLI works with:

• Next.js projects (App Router or Pages Router)
• Vite + React projects
• TypeScript (automatically enabled)
• Tailwind CSS (automatically configured)
• shadcn/ui (automatically initialized)

Polkadot API Integration

Components that require Polkadot API will automatically:

1. Install polkadot-api dependency
2. Add required chain metadata using papi CLI
3. Generate TypeScript types
4. Set up providers and configuration

Supported chains are automatically detected from component requirements.

Configuration Files

The CLI creates and manages these files:

• components.json - shadcn/ui configuration
• papi/ - Polkadot API configuration and types
• lib/utils.ts - Utility functions
• providers/polkadot-provider.tsx - API provider

Troubleshooting

Common Issues

"No project found" error:

• Run polkadot-ui init to create a new project
• Or ensure you're in a React project directory

"Component not found" error:

• Check available components with polkadot-ui list
• Verify component name spelling

Memory issues during chain metadata installation:

• The CLI automatically increases memory limits
• For very large chains, you may need to install manually

Permission issues:

• Use npx, pnpm dlx, or bunx instead of global installation
• Ensure you have write permissions in the project directory

Getting Help

• Use polkadot-ui help [command] for command-specific help
• Use --verbose flag for detailed output
• Check the GitHub repository for issues

Development Registry

During development, you can use the local registry:

# Start local registry server
pnpm dev

# Use local registry with CLI
polkadot-ui list --dev
polkadot-ui add block-number --dev

The development registry runs at http://localhost:3000 and allows you to test components before publishing.