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.
# 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.4.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 restoreto 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 the template's Bootstrap files and restyle its sample pages (Home, Counter, Weather, Error, NotFound) with Tailwind, when you haven't edited them
- Set up Tailwind CSS: choose between standalone CLI (no Node.js) or npm
- Download the Tailwind CSS v4.3.2 standalone CLI once per machine into
~/.shellui/bin(if selected). Later projects reuse it, even offline - Create component folders, config files, and CSS entry point
- Configure MSBuild integration for automatic Tailwind compilation
- 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:
shellui init --yes
This uses standalone Tailwind with default options and adds no dashboard. To script a full setup:
shellui init --yes --tailwind standalone --dashboard 02
Add Components
# 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 individual components
dotnet shellui add button input card dialog
# Add chart components
dotnet shellui add chart bar-chart line-chart pie-chart area-chart
# Add multiple components at once
dotnet shellui add table badge avatar alert
# Add the whole library, or all but a few
dotnet shellui add all
dotnet shellui add all --except chart,qr-code
# See all available components
dotnet 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:
# 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:
shellui update # every installed component
shellui update button # just one
- Your changes are kept.
shellui.jsonrecords a hash of each file as the CLI wrote it. If you've changed a file since,updateskips it and says so;shellui update card --forceoverwrites 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, thedashboard-*andauth-*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,
breadcrumbgainedbreadcrumb-listand others,tabsgainedtab-models),updateadds them with their NuGet packages and_Imports.razorusings, the same wayadddoes. - Older projects move to the shared Tailwind CLI.
updatereplacesBuild/ShellUI.targetsif 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:
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:
shellui doctor
shellui.jsonis valid andComponentsPathexists.- The Tailwind CLI is available (the shared copy in
~/.shellui/bin, a project copy, or the npm packages),Build/ShellUI.targetsexists, andwwwroot/app.cssis newer thaninput.cssand the components. - The host page (
Components/App.razororwwwroot/index.html) linksapp.css, loadsshellui.jsand 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.razorhas the ShellUI@usinglines.- The project doesn't use the
ShellUI.Componentspackage 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
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:
@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 the 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.4.0
# Local — specific version
dotnet tool install ShellUI.CLI --version 0.4.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.3.6
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
--yesflag 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
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.jscontent 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 (setSHELLUI_CACHE_DIRto move it); a copy in the project's.shellui/bintakes 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.UIis in_Imports.razor - Verify
wwwroot/app.cssexists 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.jsonto source control - Add
dotnet tool restoreto your README setup instructions - Pin to specific versions for stability
For CI/CD
- Prefer local tools for reproducibility
- Always use
--yesflag for non-interactive mode - Cache the
.dotnet/toolsdirectory 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 |