CLI Installation

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.

bash
# Install globally
dotnet tool install -g ShellUI.CLI --version 0.3.6

After installation, use the CLI without the dotnet prefix:

bash
shellui init
shellui add button input card
shellui list

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:

bash
cd your-blazor-project
shellui init

The init command will:

  1. Detect your Blazor project type (Server, WASM, Hybrid, etc.)
  2. Clean up Bootstrap files if present
  3. Set up Tailwind CSS — choose between standalone CLI (no Node.js) or npm
  4. Download the Tailwind CSS v4.3.2 standalone CLI once per machine into ~/.shellui/bin (if selected). Later projects reuse it, even offline
  5. Create component folders, config files, and CSS entry point
  6. 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.3.2
  • npm: Traditional setup with Node.js — uses tailwindcss@^4.3.2

Non-Interactive Mode

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

bash
shellui init --yes

This uses standalone Tailwind with default options — no prompts.


Add Components

bash
# Add individual components
shellui add button input card dialog

# Add chart components
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

Updating and removing components

bash
shellui update            # every installed component
shellui update card       # one component
shellui remove button card

From 0.3.5:

  • update keeps your changes. shellui.json records a hash of each file as the CLI wrote it. If you've changed a file since, update skips it and says so; shellui update card --force overwrites it. Files installed by an earlier CLI have no hash, so on that first update app-sidebar and the dashboard-* layouts are kept when they differ from the template, and everything else is rewritten. Commit first so you can review the changes.
  • update installs dependencies a component gained since you added it, with their NuGet packages and _Imports.razor usings, and moves the project onto the shared Tailwind CLI (it replaces Build/ShellUI.targets unless you edited it).
  • add never downgrades a NuGet package the project already has at the same or a newer version.
  • remove deletes the files wherever ComponentsPath points, removes the dashboard layouts, and lists files that still use a removed layout.

Chart Components Dependency

Chart components require the ApexCharts NuGet package:

bash
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
│       ├── BarChart.razor
│       └── ...
├── Variants/                  # CVA variant definitions
│   ├── ButtonVariants.cs
│   └── ...
├── wwwroot/
│   ├── input.css              # Tailwind input
│   └── app.css                # Compiled CSS (auto-generated)
├── .shellui/
│   └── .gitignore             # keeps .shellui/ out of git (an optional per-project Tailwind CLI goes in bin/)
├── 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:

razor
@using YourProject.Components.UI

Or import in individual Razor files as needed.


Version Management

Check Current Version

bash
# Global tool
shellui --version

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

# Local tool
dotnet tool list | findstr ShellUI

Update to the Latest 0.3 Release

bash
# Update global tool
dotnet tool update -g ShellUI.CLI --version 0.3.6

# Update local tool
dotnet tool update ShellUI.CLI --version 0.3.6

Install a Specific Version

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

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

Downgrade to Previous Version

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

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

# Uninstall local tool
dotnet tool uninstall ShellUI.CLI

CI/CD Setup

GitHub Actions — Global Tool

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

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

- name: Add components
  run: shellui add button input card
yaml
- 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

yaml
- script: dotnet tool install -g ShellUI.CLI --version 0.3.6
  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

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

# Or restart your terminal / command prompt

Tailwind CSS Not Compiling

  • Ensure you're using Tailwind CSS v4.3.2
  • 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
  • The standalone Tailwind CLI lives in ~/.shellui/bin, shared by every project (set SHELLUI_CACHE_DIR to move it); a copy in the project's .shellui/bin takes precedence. If the download failed, the build tries again and warns with the URL and target path

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)

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

Version Conflicts

bash
# Check what's installed
dotnet tool list -g

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

Best Practices

For Individual Developers

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

For Teams

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

For CI/CD

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

Quick Reference

Task Global Command Local Command
Install CLI dotnet tool install -g ShellUI.CLI --version 0.3.6 dotnet tool install ShellUI.CLI --version 0.3.6
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 --version 0.3.6 dotnet tool update ShellUI.CLI --version 0.3.6
Uninstall CLI dotnet tool uninstall -g ShellUI.CLI dotnet tool uninstall ShellUI.CLI
Restore (teams) — dotnet tool restore

Rejoining the server...

Rejoin failed... trying again in seconds.

Failed to rejoin.
Please retry or reload the page.

The session has been paused by the server.

Failed to resume the session.
Please retry or reload the page.