# Installation

> Install the ShellDocs CLI, add the framework to a Blazor project.

Source: https://shelldocs.shellui.dev/docs/getting-started/installation

Two things to install: the **CLI** (a .NET global tool) and the **framework packages** (referenced from your docs project). Most consumers use the CLI to scaffold a fresh project, which wires the packages automatically.

## Prerequisites

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `.NET SDK` (required) | `10.0+` |  | .NET 10 or newer. Verify with dotnet --version. |
| `git` | `any` |  | For version control. Not strictly required to run ShellDocs : required for publishing to GitHub Pages / Cloudflare / Netlify from a repo. |

## Install the CLI

`ShellDocs.CLI` is a .NET global tool. Install once, use from any directory.

```bash
dotnet tool install -g ShellDocs.CLI --prerelease
```

> **Why --prerelease**
>
> The `--prerelease` flag is required while ShellDocs is on `0.x.y-alpha` versions. `dotnet tool install` skips prerelease packages by default. Drop the flag once `1.0` ships.

Verify:

```bash
shelldocs --help
```

You should see `init`, `add`, `dev` and `build` in the command list. (`preview` is listed too, but is not implemented yet.)

## Update the CLI

```bash
dotnet tool update -g ShellDocs.CLI --prerelease
```

Pulls the latest published version from nuget.org.

## The framework packages

If you're scaffolding via `shelldocs init`, the CLI adds these to your `.csproj` automatically. If you're wiring an existing Blazor project by hand, add:

**dotnet CLI**

```bash
dotnet add package ShellDocs.Components --prerelease
dotnet add package ShellDocs.Tokens --prerelease
```

**PackageReference**

```xml
<PackageReference Include="ShellDocs.Components" Version="0.1.17-alpha" />
<PackageReference Include="ShellDocs.Tokens" Version="0.1.17-alpha" />
```

`ShellDocs.Core` and `ShellDocs.Markdown` come in transitively : no need to reference them directly.

## The package family

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `ShellDocs.CLI` | `global tool` |  | shelldocs init, add, dev, build. Installed once, works from any directory. |
| `ShellDocs.Components` | `RCL` |  | The chrome (layout, sidebar, search, header) and content primitives (Callout, Card, Steps, CodeGroup, TypeTable, more). |
| `ShellDocs.Tokens` | `RCL` |  | Shared CSS variables. shadcn-compatible names for interop with ShellUI and other design systems. |
| `ShellDocs.Core` | `library (transitive)` |  | Navigation graph, search index, markdown plain-text extraction. |
| `ShellDocs.Markdown` | `library (transitive)` |  | Markdig pipeline, frontmatter parser, razor:preview and inline-component slot extractor. |

## Next

- [Quick start](https://shelldocs.shellui.dev/docs/getting-started/quick-start.md): Scaffold a fresh site and see it running in ~5 minutes.
- [Project structure](https://shelldocs.shellui.dev/docs/getting-started/project-structure.md): What shelldocs init created, and what each folder does.