# CLI Installation > Install ShellUI via the CLI tool for full component ownership and automatic Tailwind setup Source: https://shellui.dev/docs/v0.3/installation/cli 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 Install** ### 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 ``` **Local Install (Teams)** ### 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.** ```bash # 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: ```json { "version": 1, "isRoot": true, "tools": { "shellui.cli": { "version": "0.3.6", "commands": ["shellui"] } } } ``` Local tools require the `dotnet` prefix: ```bash 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: **Global** ```bash cd your-blazor-project shellui init ``` **Local** ```bash cd your-blazor-project dotnet 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 **Global** ```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 ``` **Local** ```bash # 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 ```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 ``` ### GitHub Actions — Local Tool (Recommended) ```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 **Windows** ```powershell # Add .NET tools to PATH (PowerShell) $env:PATH += ";$env:USERPROFILE\.dotnet\tools" # Or restart your terminal / command prompt ``` **macOS / Linux** ```bash # 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.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` |