Install ShellUI via the CLI tool for full component ownership and automatic Tailwind setup

The ShellUI CLI copies component source files directly into your project, giving you full ownership and customization control. It also handles Tailwind CSS setup, Bootstrap cleanup, folder creation, and MSBuild integration automatically.

Install the CLI Tool

Global Installation

Global installation makes the shellui command available system-wide. Best for individual developers, quick prototyping, and personal projects.

# Install globally
dotnet tool install -g ShellUI.CLI

After installation, use the CLI without the dotnet prefix:

shellui init
shellui add button input card
shellui list

Local Tool Installation

Local installation locks the CLI version per-project and shares it via source control. Best for teams, CI/CD pipelines, and enterprise projects.

# Step 1: Create a tool manifest (one-time, in project root)
dotnet new tool-manifest

# Step 2: Install as a local tool
dotnet tool install ShellUI.CLI

This creates a .config/dotnet-tools.json file — commit it to source control:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "shellui.cli": {
      "version": "0.2.0",
      "commands": ["shellui"]
    }
  }
}

Local tools require the dotnet prefix:

dotnet shellui init
dotnet shellui add button input card
dotnet shellui list

Team onboarding: New team members just run dotnet tool restore to get the exact same CLI version.

Global vs Local — When to Use Which

Aspect	Global (`-g`)	Local (manifest)
Command	`shellui init`	`dotnet shellui init`
Install location	User profile	Project directory
Sharing	Each dev installs separately	Auto-restored via manifest
Version lock	Latest (unless pinned)	Locked in manifest file
CI/CD	Requires explicit install step	`dotnet tool restore`
Best for	Individual developers	Teams & CI/CD

Initialize Your Project

Navigate to your Blazor project directory and run init:

cd your-blazor-project
shellui init

cd your-blazor-project
dotnet shellui init

The init command will:

Detect your Blazor project type (Server, WASM, Hybrid, etc.)
Clean up Bootstrap files if present
Set up Tailwind CSS — choose between standalone CLI (no Node.js) or npm
Download Tailwind CSS v4.1.18 standalone CLI (if selected)
Create component folders, config files, and CSS entry point
Configure MSBuild integration for automatic Tailwind compilation

Choose your Tailwind CSS setup method when prompted:

Standalone CLI (recommended): No Node.js required — uses Tailwind v4.1.18
npm: Traditional setup with Node.js — uses tailwindcss@^4.1.18

Non-Interactive Mode

For CI/CD or automated environments, use the --yes flag to accept all defaults:

shellui init --yes

This uses standalone Tailwind with default options — no prompts.

Add Components

# Add individual components
shellui add button input card dialog

# Add chart components (new in v0.2.0)
shellui add chart bar-chart line-chart pie-chart area-chart

# Add multiple components at once
shellui add table badge avatar alert

# See all available components
shellui list

# Add individual components
dotnet shellui add button input card dialog

# Add chart components (new in v0.2.0)
dotnet shellui add chart bar-chart line-chart pie-chart area-chart

# Add multiple components at once
dotnet shellui add table badge avatar alert

# See all available components
dotnet shellui list

Chart Components Dependency

Chart components (new in v0.2.0) require the ApexCharts NuGet package:

dotnet add package Blazor-ApexCharts

Project Structure

After initialization and adding components, your project will have:

YourProject/
├── Components/
│   └── UI/                    # ShellUI components (source files)
│       ├── Button.razor
│       ├── Input.razor
│       ├── Card.razor
│       ├── Chart.razor        # New in v0.2.0
│       ├── BarChart.razor     # New in v0.2.0
│       └── ...
├── Variants/                  # CVA variant definitions
│   ├── ButtonVariants.cs
│   └── ...
├── wwwroot/
│   ├── input.css              # Tailwind input
│   └── app.css                # Compiled CSS (auto-generated)
├── .shellui/
│   └── bin/                   # Tailwind CLI binary (standalone only)
├── tailwind.config.js         # Tailwind configuration
├── shellui.json               # ShellUI configuration
└── Build/
    └── ShellUI.targets        # MSBuild integration

Import Components

After adding components, import them in your _Imports.razor:

@using YourProject.Components.UI

Or import in individual Razor files as needed.

Version Management

Check Current Version

# Global tool
shellui --version

# List all global .NET tools
dotnet tool list -g | findstr ShellUI

# Local tool
dotnet tool list | findstr ShellUI

Update to Latest Version

# Update global tool
dotnet tool update -g ShellUI.CLI

# Update local tool
dotnet tool update ShellUI.CLI

Install a Specific Version

# Global — specific version
dotnet tool install -g ShellUI.CLI --version 0.2.0

# Local — specific version
dotnet tool install ShellUI.CLI --version 0.2.0

Downgrade to Previous Version

# Uninstall current, then install the version you need
dotnet tool uninstall -g ShellUI.CLI
dotnet tool install -g ShellUI.CLI --version 0.1.0

Uninstall

# Uninstall global tool
dotnet tool uninstall -g ShellUI.CLI

# Uninstall local tool
dotnet tool uninstall ShellUI.CLI

CI/CD Setup

GitHub Actions — Global Tool

- name: Install ShellUI CLI
  run: dotnet tool install -g ShellUI.CLI

- name: Initialize ShellUI
  run: shellui init --yes

- name: Add components
  run: shellui add button input card

GitHub Actions — Local Tool (Recommended)

- name: Restore tools
  run: dotnet tool restore

- name: Initialize ShellUI
  run: dotnet shellui init --yes

- name: Add components
  run: dotnet shellui add button input card

Azure DevOps

- script: dotnet tool install -g ShellUI.CLI
  displayName: 'Install ShellUI CLI'

- script: shellui init --yes
  displayName: 'Initialize ShellUI'

- script: shellui add button input card
  displayName: 'Add ShellUI Components'

Tip: Use the --yes flag in CI/CD for non-interactive mode (auto-accepts defaults).

Troubleshooting

CLI Not Found After Installation

# Add .NET tools to PATH (PowerShell)
$env:PATH += ";$env:USERPROFILE\.dotnet\tools"

# Or restart your terminal / command prompt

# Add .NET tools to PATH
export PATH="$PATH:$HOME/.dotnet/tools"

# Make it permanent — add to .bashrc or .zshrc
echo 'export PATH="$PATH:$HOME/.dotnet/tools"' >> ~/.zshrc
source ~/.zshrc

Tailwind CSS Not Compiling

Ensure you're using Tailwind CSS v4.1.18
Check your tailwind.config.js content paths include **/*.razor
Verify Node.js is installed (if using npm method)
Run dotnet build — CLI method compiles Tailwind automatically via MSBuild

Components Not Rendering

Check that components are in the Components/UI/ folder
Ensure @using YourProject.Components.UI is in _Imports.razor
Verify wwwroot/app.css exists and is linked in your layout
Check browser dev tools for missing CSS

Tool Restore Fails (Local Installation)

# Clear NuGet cache and retry
dotnet nuget locals all --clear
dotnet tool restore

Version Conflicts

# Check what's installed
dotnet tool list -g

# Clean reinstall
dotnet tool uninstall -g ShellUI.CLI
dotnet tool install -g ShellUI.CLI

Best Practices

For Individual Developers

Use global installation for convenience
Update regularly: dotnet tool update -g ShellUI.CLI
Check for updates before starting new projects

For Teams

Use local tool installation with manifest
Commit .config/dotnet-tools.json to source control
Add dotnet tool restore to your README setup instructions
Pin to specific versions for stability

For CI/CD

Prefer local tools for reproducibility
Always use --yes flag for non-interactive mode
Cache the .dotnet/tools directory if using global installation

Quick Reference

Task	Global Command	Local Command
Install CLI	`dotnet tool install -g ShellUI.CLI`	`dotnet tool install ShellUI.CLI`
Initialize project	`shellui init`	`dotnet shellui init`
Add components	`shellui add button card`	`dotnet shellui add button card`
List components	`shellui list`	`dotnet shellui list`
Check version	`shellui --version`	`dotnet tool list`
Update CLI	`dotnet tool update -g ShellUI.CLI`	`dotnet tool update ShellUI.CLI`
Uninstall CLI	`dotnet tool uninstall -g ShellUI.CLI`	`dotnet tool uninstall ShellUI.CLI`
Restore (teams)	—	`dotnet tool restore`

CLI Installation