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.
# Install globally
dotnet tool install -g ShellUI.CLI --version 0.3.6
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 --version 0.3.6
This creates a .config/dotnet-tools.json file — commit it to source control:
{
"version": 1,
"isRoot": true,
"tools": {
"shellui.cli": {
"version": "0.3.6",
"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 Bootstrap files if present
- 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
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:
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
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
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
Updating and removing components
shellui update # every installed component
shellui update card # one component
shellui remove button card
From 0.3.5:
updatekeeps your changes.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 by an earlier CLI have no hash, so on that first updateapp-sidebarand thedashboard-*layouts are kept when they differ from the template, and everything else is rewritten. Commit first so you can review the changes.updateinstalls dependencies a component gained since you added it, with their NuGet packages and_Imports.razorusings, and moves the project onto the shared Tailwind CLI (it replacesBuild/ShellUI.targetsunless you edited it).addnever downgrades a NuGet package the project already has at the same or a newer version.removedeletes the files whereverComponentsPathpoints, removes the dashboard layouts, and lists files that still use a removed layout.
Chart Components Dependency
Chart components 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
│ ├── 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 0.3 Release
# 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
# 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
# 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 --version 0.3.6
- 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 --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
--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
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. 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.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 --version 0.3.6
Best Practices
For Individual Developers
- Use global installation for convenience
- Update regularly:
dotnet tool update -g ShellUI.CLI --version 0.3.6 - 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 --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 |