CLI

Introduction

The polka-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 polka-ui@latest add <component-name>

Installation

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

# Using npx
npx polka-ui@latest

# Using pnpm
pnpm dlx polka-ui@latest

# Using bun
bunx polka-ui@latest

Global Options

All commands support these global options:

Commands

add

Add a component to your project.

polka-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
polka-ui add block-number

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

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

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

# Verbose output
polka-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.

polka-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
polka-ui init

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

# Use development registry
polka-ui init --dev

# Verbose output
polka-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.

polka-ui list [options]

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

Examples:

# List all components
polka-ui list

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

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

Output includes:

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

help

Show help information.

polka-ui help [command]

Examples:

# Show general help
polka-ui help

# Show help for specific command
polka-ui help add
polka-ui help init
polka-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
polka-ui init --yes

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

Development Workflow

Working with local registry during development:

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

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

Existing Project

Add components to an existing React project:

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

# Force overwrite if you need to update files
polka-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
• lib/config.papi.ts - Polkadot configuration
• providers/polkadot-provider.tsx - API provider

Troubleshooting

Common Issues

"No project found" error:

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

"Component not found" error:

• Check available components with polka-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 polka-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
polka-ui list --dev
polka-ui add block-number --dev

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