# `shelldocs init`
> Scaffold a fresh docs site OR attach ShellDocs to an existing Blazor project.
Source: https://shelldocs.shellui.dev/docs/cli/init
`shelldocs init` is the "get to running docs" command. Two modes: **create** (default) makes a fresh Blazor Web App under `docs/.Docs/` and wires everything for you, **attach** (`--attach`) augments an existing Blazor project in place without touching its `Program.cs`.
## Synopsis
```bash
shelldocs init [path] [--dir ] [--attach] [--yes] [--theme ]
```
## Create mode (default)
Scaffolds a fresh Blazor Web App and patches the template to be a working ShellDocs site : one command from empty directory to a running docs project.
```bash
shelldocs init MyDocs
```
Produces `MyDocs/` in the current directory (or, when called with no `path`, `docs/.Docs/`).
**1. Runs `dotnet new blazor -o `**
Scaffolds a fresh Blazor Web App using the standard template. Fails fast if the target directory exists and isn't empty : use `--attach` instead of overwriting.
**2. Adds package references**
Injects `` and `` into the freshly-created `.csproj`. Both are pinned to the CLI's own version, so the scaffold always matches the tool that made it.
**3. Adds content copy-to-output**
Inserts a `` group so `dotnet publish` carries the markdown corpus into the publish output.
**4. Writes starter content**
Creates `content/docs/introduction.md` and `content/docs/meta.json` : the minimum a ShellDocs site needs to render.
**5. Writes `Components/Pages/DocsPage.razor`**
The single-page router that serves every `/docs/**` URL from the `.md` files under `content/`. You don't edit this : it's just a `` around a ``, with `` for a URL that has no page.
**6. Strips the fresh-template chrome**
Deletes `Counter.razor`, `Weather.razor`, `NavMenu.razor`, `MainLayout.razor.css`, `Home.razor.css`. Rewrites `MainLayout.razor` as a bare pass-through and replaces `Home.razor` with the ShellDocs welcome page.
**7. Patches `Program.cs`**
Adds `using ShellDocs.Components;`, `builder.WebHost.UseStaticWebAssets();`, and `builder.Services.AddShellDocs(...)` : anchoring on the exact template shape produced by `dotnet new blazor`. The `AddShellDocs` call turns on [llms.txt for AI agents](https://shelldocs.shellui.dev/docs/guides/llms-txt.md) with `o.EnableLlmsTxt(...)`, its options commented out, and sets the [colour preset](https://shelldocs.shellui.dev/docs/theming.md#colour-presets) from `--theme`.
**8. Patches `Components/App.razor`**
Adds the `_content/ShellDocs.Tokens/tokens.css` and component CSS links, the theme-bootstrap script, and `shelldocs.js` + Shiki loader. Also switches `` to `` so interactive components (theme toggle, search, tabs) come alive.
**9. Registers with the nearest solution**
Walks up from the working directory looking for a `.slnx` or `.sln` (stops at the repo root or 6 levels up). If one is found and doesn't already reference the project, runs `dotnet sln add`.
> **Idempotent**
>
> Re-running `shelldocs init` on the same directory won't clobber your edits : every step checks for the target artifact and skips if it's already present.
### Path inference
When called with no `path` argument, the target is `docs/.Docs/`. So running from `~/code/my-library/` produces `~/code/my-library/docs/my-library.Docs/`.
### Site name
The header brand is derived from the target directory name, stripping a trailing `.Docs` suffix. `my-library.Docs` → header shows "my-library".
### GitHub prompt
Interactive mode asks for `owner/repo` (blank to skip). The answer wires the GitHub link in the header and is used by search / social meta. Pass `--yes` to skip the prompt.
## Attach mode (`--attach`)
Augments an existing Blazor project in place. Never touches your `Program.cs` : instead emits `SHELLDOCS_SETUP.md` with copy-paste snippets so you can wire ShellDocs into your custom middleware, auth, or DI without a merge conflict.
```bash
shelldocs init --attach --dir path/to/my/blazor/project
```
**1. Verifies the target is a Blazor project**
Checks the `.csproj` for `Microsoft.NET.Sdk.Web`, `.Razor`, `.BlazorWebAssembly`, or a `Microsoft.AspNetCore.Components` reference. Bails if none match.
**2. Adds package references**
Same as create mode.
**3. Writes starter content**
Same as create mode.
**4. Writes DocsPage.razor**
Same as create mode.
**5. Writes SHELLDOCS_SETUP.md**
A per-project setup guide with copy-paste snippets for the exact `AddShellDocs`, `MapShellDocs`, and `App.razor` additions your project needs. This is what create mode does automatically : attach mode leaves it to you.
## Options
| Name | Type | Default | Description |
|------|------|---------|-------------|
| `path` | `argument` | | Target directory for the new docs project. Default: docs/{CwdName}.Docs. Ignored with --attach. |
| `--dir` | `string` | `cwd` | Working directory. With --attach, the project directory to augment. |
| `--attach` | `bool` | `false` | Attach mode : augment an existing Blazor project instead of creating one. |
| `--yes` | `bool` | `false` | Non-interactive : skip the GitHub-repo prompt, take defaults everywhere. |
| `--theme` | `string` | `graphite` | Colour preset: graphite, harbor, lagoon, forest, savanna, ember or jacaranda. Writes o.Theme = ShellDocsTheme.{Preset} into Program.cs; graphite, the default, leaves it as a commented-out example. See Theming. |
## Exit codes
| Name | Type | Default | Description |
|------|------|---------|-------------|
| `0` | `ok` | | Scaffolding completed (create) or attach patches wrote. |
| `1` | `usage` | | Target directory exists and isn't empty (create), or target is not a Blazor project (attach), or missing/invalid arguments. |
| `other` | `pass-through` | | dotnet new blazor exit code propagated (create mode). |
## See also
- [shelldocs add](https://shelldocs.shellui.dev/docs/cli/add.md): Scaffold a starter page after init.
- [Project structure](https://shelldocs.shellui.dev/docs/getting-started/project-structure.md): Tour of what init produced.