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.

The CLI runs on .NET 8 or later and sets up Blazor projects on .NET 8, 9 and 10. (The 0.3 line and the 0.4 prereleases needed the .NET 10 runtime.)

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

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 the template's Bootstrap files and restyle its sample pages (Home, Counter, Weather, Error, NotFound) with Tailwind, when you haven't edited them
  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
  7. Offer a dashboard layout: sticky header (dashboard-02), scrolling header (dashboard-01), or none. See the dashboard guide

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

In an app created with --auth Individual, init also keeps the /Account pages working. See Authentication.

Options

Option What it does
--yes No prompts. Uses standalone Tailwind and adds no dashboard unless the options below say otherwise
--tailwind <method> standalone or npm. Picks the Tailwind setup and skips that prompt
--dashboard <layout> 01, 02 or none. Sets up a dashboard layout, or skips it, without asking
--replace-layout Lets the dashboard replace a layout you have customized
--style <style> default, new-york or minimal
--force Reinitializes a project that already has shellui.json

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 and adds no dashboard. To script a full setup:

bash
shellui init --yes --tailwind standalone --dashboard 02

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

# Add the whole library, or all but a few
shellui add all
shellui add all --except chart,qr-code

# See all available components
shellui list

add takes names separated by spaces, commas, or both; shellui list prints the 98 names it accepts. Dependencies (parts, models, variants, NuGet packages and _Imports.razor usings) are installed with each component, and --force overwrites a file that's already there.

Adding everything

shellui add all installs every component shellui list shows except the blocks (dashboard-01, dashboard-02, auth-01, auth-02, auth-03), which rewire the app and are added by name. Components already installed are skipped. --except leaves components out, along with anything that needs them: --except chart also leaves out bar-chart, line-chart and the other charts, so Blazor-ApexCharts isn't added.

Blocks

Blocks are larger pieces that also wire themselves into the app:

bash
# Dashboard layout: sidebar, header, breadcrumb, theme toggle
shellui add dashboard-02

# Sign-in page layouts for ASP.NET Core Identity apps
shellui add auth-01

See the dashboard guide and Authentication.

Updating installed components

After updating the CLI, rewrite the components you installed from the new templates:

bash
shellui update          # every installed component
shellui update button   # just one
  • Your changes are kept. 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 before 0.4.0-alpha.2 have no hash, so on that first update the blocks you're meant to edit (app-sidebar, sidebar-account, the dashboard-* and auth-* layouts) are kept when they differ from the template, and everything else is rewritten.
  • New dependencies are installed. When a component gained parts since you installed it (in 0.4, breadcrumb gained breadcrumb-list and others, tabs gained tab-models), update adds them with their NuGet packages and _Imports.razor usings, the same way add does.
  • Older projects move to the shared Tailwind CLI. update replaces Build/ShellUI.targets if you haven't edited it, adds .shellui/.gitignore, and deletes the project's copy of the Tailwind CLI when it matches the shared one.

update has no diff or merge, so commit first to review the changes. It reports how many components were updated, skipped and failed. When a template's API changed, run shellui migrate afterwards to update your pages.

Migrating your pages

shellui migrate rewrites your own pages for the template API changes listed in the release notes, after update has replaced the components:

bash
shellui migrate --dry-run          # show the changes only
shellui migrate                    # show each change and ask before writing
shellui migrate date-picker pagination
shellui migrate --yes              # write without asking (needed when the terminal isn't interactive)

It reads the project's .razor and .cs files, but not the installed components under ComponentsPath, or bin, obj and node_modules. With no names it runs every migration:

Name Change
input Input.InputVariant.Error → InputVariant.Error
date-picker SelectedDate, SelectedDateChanged and @bind-SelectedDate → Value, ValueChanged and @bind-Value, on <DatePicker> only
time-picker The same for <TimePicker>'s SelectedTime
pagination OnPageChange → CurrentPageChanged, except on a tag that already uses @bind-CurrentPage
calendar Lists Calendar.SelectedDateChanged handlers that take a DateTime; they need a DateTime?. Nothing is rewritten

Commit first, and build the app afterwards.

Checking the setup

shellui doctor checks the project and prints a fix for each problem it finds:

bash
shellui doctor
  • shellui.json is valid and ComponentsPath exists.
  • The Tailwind CLI is available (the shared copy in ~/.shellui/bin, a project copy, or the npm packages), Build/ShellUI.targets exists, and wwwroot/app.css is newer than input.css and the components.
  • The host page (Components/App.razor or wwwroot/index.html) links app.css, loads shellui.js and has the theme script.
  • An interactive render mode is set in App.razor. When only some pages set one, components on the other pages don't respond to clicks.
  • Every installed component's file exists and its dependencies are installed.
  • _Imports.razor has the ShellUI @using lines.
  • The project doesn't use the ShellUI.Components package and CLI-installed components together.

It exits with code 1 when it finds a problem, so it can run in CI; warnings, such as a stale app.css, don't change the exit code. In a Razor class library it skips the host page checks, which apply to each app that uses the library.

Removing components

bash
shellui remove button
shellui remove button card dialog

remove deletes the component files and their shellui.json entries, wherever ComponentsPath points. Layout blocks such as dashboard-02 and auth-01 are removed from Components/Layout, and remove lists the files that still use the layout (usually Routes.razor) so you can point them at another one. It doesn't remove components that depend on the removed one.

NuGet dependencies

Some components need a NuGet package: chart needs Blazor-ApexCharts, data-table needs System.Linq.Dynamic.Core, and qr-code needs QRCoder. add references it if the project doesn't, and raises an older version to the one ShellUI needs. It never downgrades: a version that's already the same or newer is left alone (including one set in Directory.Packages.props), as are floating versions such as 7.* and ranges.


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 Version

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

# Update local tool
dotnet tool update ShellUI.CLI

Install a Specific Version

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

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

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.3.6

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

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

Start with shellui doctor

shellui doctor checks the setup described on this page (Tailwind CLI, build targets, host page, render mode, installed files, _Imports.razor) and says how to fix each problem it finds. See Checking the setup.

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. After a fresh clone the build uses the shared copy, or downloads it (resuming over slow connections) and warns with the URL and target path if it can't
  • A project set up with 0.3 keeps the old build step until you run shellui update, which switches it to the shared CLI

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

Best Practices

For Individual Developers

  1. Use global installation for convenience
  2. Update regularly: dotnet tool update -g ShellUI.CLI
  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 dotnet tool install ShellUI.CLI
Initialize project shellui init dotnet shellui init
Add components shellui add button card dotnet shellui add button card
Add every component shellui add all dotnet shellui add all
List components shellui list dotnet shellui list
Update components shellui update dotnet shellui update
Rewrite pages after an update shellui migrate dotnet shellui migrate
Check the setup shellui doctor dotnet shellui doctor
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

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.