--- title: "CLI" description: "Use the nimbus-docs CLI to install registry features, migrate package APIs, review copied code, and check content." --- > Documentation Index > Fetch the complete documentation index at: https://docs.klounge.kr/llms.txt > Use this file to discover all available pages before exploring further. # CLI The `nimbus-docs` CLI lists what's in the registry, installs it, records what you own in [`nimbus.json`](/project-structure), shows what's fallen behind upstream, and lints your MDX content. ## `nimbus-docs list` Lists every installable component, utility, and feature. ```sh npx list pnpm dlx list yarn dlx list bunx list ``` Filter by type: ```sh npx list --type ui pnpm dlx list --type ui yarn dlx list --type ui bunx list --type ui ``` ```sh npx list --type lib pnpm dlx list --type lib yarn dlx list --type lib bunx list --type lib ``` ```sh npx list --type feature pnpm dlx list --type feature yarn dlx list --type feature bunx list --type feature ``` Running `nimbus-docs add` with no slug shows the same list. ## `nimbus-docs add ` Registry entries use two install modes based on their type. Special `adapter-` slugs use a third flow that rewrites project configuration. ### Components and utilities For `registry:ui` and `registry:lib` slugs, the CLI resolves dependencies, copies files into your repo, and installs any npm packages they need. ```sh npx add badge pnpm dlx add badge yarn dlx add badge bunx add badge ``` 1. **Resolve dependencies** Walks the slug's `registryDependencies` and any npm `dependencies` it needs. 2. **Copy files** Drops each file into the right path under `src/components/ui/`, `src/lib/`, or wherever the entry declares. 3. **Update package.json** Adds npm dependencies if they're not already present. If a component is already installed, `add` keeps your copy — it never clobbers files you own. Pass `--overwrite` to replace them with the registry version (the upgrade path); review the change with `git diff`: ```sh npx add badge --overwrite pnpm dlx add badge --overwrite yarn dlx add badge --overwrite bunx add badge --overwrite ``` For `add`, `--yes` assents to prompts such as dependency installs but still keeps existing files. Use `--overwrite` when you actually mean "replace my files." Once installed, the component lives in your repo. Edit freely — there's no upstream API to break. Each `add` also appends an entry to your [`nimbus.json`](/project-structure) — slug, source registry, the registry release it came from, and a content hash — so later upgrades can track what you own. ### Features For `registry:feature` slugs, there's nothing to copy. The recipe is a markdown prompt the agent reads, adapts to your project, and applies. ```sh npx add 404-page pnpm dlx add 404-page yarn dlx add 404-page bunx add 404-page ``` If the CLI detects a coding agent in the environment, it prints the recipe to stdout for the agent to consume. Otherwise it prints pipe instructions you can run yourself: ```sh npx add 404-page --print | claude pnpm dlx add 404-page --print | claude yarn dlx add 404-page --print | claude bunx add 404-page --print | claude ``` ```sh npx add 404-page --print | codex pnpm dlx add 404-page --print | codex yarn dlx add 404-page --print | codex bunx add 404-page --print | codex ``` Use `--print` to force the markdown output, skipping detection. ### Server adapters For `adapter-cloudflare`, `adapter-vercel`, `adapter-netlify`, and `adapter-node`, the CLI installs the Astro adapter and rewrites the marked `output` block in `astro.config`. It refuses to replace a different adapter or a non-literal `output` value. ```sh npx add adapter-cloudflare pnpm dlx add adapter-cloudflare yarn dlx add adapter-cloudflare bunx add adapter-cloudflare ``` `adapter-cloudflare` adds request rendering when the Nimbus config has no explicit rendering policy. Existing policies are preserved; imported or ambiguous configurations receive a coding-agent handoff instead of a speculative rewrite. The command creates a server-compatible `wrangler.jsonc` when none exists or replaces an unchanged Nimbus static config; custom JSONC and alternate JSON/TOML configs stay untouched. After completing the adapter install, expect: ```ts const nimbusConfig = defineNimbusConfig({ rendering: { default: "request" }, // ... }); export default defineConfig({ output: "server", adapter: cloudflare({ prerenderEnvironment: "node" }), integrations: [nimbus(nimbusConfig)], }); ``` When the command runs inside a detected coding agent, it emits a versioned recipe so the agent can safely adapt project-owned or split configuration. From a regular shell, use `--print` to request that recipe explicitly: ```sh npx add adapter-cloudflare --print | claude pnpm dlx add adapter-cloudflare --print | claude yarn dlx add adapter-cloudflare --print | claude bunx add adapter-cloudflare --print | claude ``` Always run the project’s production build afterward. See [Rendering policy](/configuration#rendering-policy) for per-collection build/request overrides. The equivalent long form is `nimbus-docs add server-output --adapter `. ## `nimbus-docs init` Writes a [`nimbus.json`](/project-structure) for a project that lacks one — a repo scaffolded before the record existed, an existing Astro site adopting Nimbus, or a deleted record. Fresh scaffolds already have one, so `init` is the on-ramp for everything else. ```sh npx init pnpm dlx init yarn dlx init bunx init ``` It scans your installed components, matches each against the registry, and writes what it can recover — marking, never guessing: - **matched** — byte-identical to the registry copy. - **modified** — you've edited it; the record keeps the source identity so upgrades can still compare. - **hand-authored** — yours, from no registry. The starter version, `templates-v*` tag, and previously reviewed Nimbus version can't be recovered from the repo alone, so they're left blank (and flagged `reconstructed`). Use `migrate --from ` to establish the upgrade range. ```sh npx init --root packages/docs pnpm dlx init --root packages/docs yarn dlx init --root packages/docs bunx init --root packages/docs ``` ```sh npx init --force pnpm dlx init --force yarn dlx init --force bunx init --force ``` ## Keeping up to date Package managers update Nimbus itself; Nimbus updates known API usage and reviews copied code: ```sh pnpm up @cloudflare/nimbus-docs --latest pnpm exec nimbus-docs migrate pnpm exec nimbus-docs outdated ``` ### `nimbus-docs migrate` Composes every declared breaking change between the project's `lastReviewedNimbusVersion` and the installed Nimbus version. It shows complete diffs for statically proven edits and bounded review tasks for everything else. Customized or ambiguous code is never forced. Existing projects without a reviewed baseline must provide the exact Nimbus version whose migrations they last completed: ```sh pnpm exec nimbus-docs migrate --from PREVIOUS_VERSION ``` Use `--dry-run` or `--diff` for a read-only plan, `--yes --json` for an agent-safe apply loop, and `--print` for a self-contained Markdown handoff. A computed Astro `srcDir` can be supplied explicitly with `--src-dir `. Nimbus applies an edit only when it recognizes the source and can prove the change is safe. Customized or ambiguous code remains unchanged and is returned as a review task. `migrate --print` emits that task for any agent or workflow; Nimbus does not launch one itself. Migration output includes the selected version range, required reviews, planned diffs, blockers, and errors. Files outside the reported scan boundary are not claimed as checked. Upgrade entries marked optional appear after required work in `migrate` and as informational Package API notes in `outdated`. They describe improvements that every existing site can skip without changing its build or output, so they never stop a build. Run `migrate --yes` to record them as reviewed when you are ready. After completing all reported work, explicitly confirm it and advance the committed reviewed baseline: ```sh pnpm exec nimbus-docs migrate --from PREVIOUS_VERSION --yes ``` Repeat `--from` only when the project has no recorded baseline. A clean interactive rerun asks before recording the reviewed version; agents provide that consent with `--yes`. Nimbus never records completion while a detectable migration remains. Then run `outdated` to review user-owned starter and registry code, followed by `nimbus-docs check`, `astro check`, and the production build. The `migrate` output is the version-selected upgrade guide. ### `nimbus-docs outdated` The read-only "am I behind?" overview across package APIs, starter files, and registry components: ```sh npx outdated pnpm dlx outdated yarn dlx outdated bunx outdated ``` - **Package APIs** — points pending source migrations and version-selected reviews to `migrate`. - **Registry components** — compares each recorded content hash against the current registry and classifies the recorded local footprint. Registry updates remain review-only because overwrite can also affect dependencies. - **Starter files** — compares your scaffolded files against the upstream `templates-v*` tag, including additions and removals. Because those files came from a tag that was never in your git history, plain `git diff` can't show this. Content files are hidden by default (`--all` to include them). Pass `--json` for deterministic agent-readable findings. Projects without complete `nimbus.json` provenance still receive Package API results and an explicit partial-coverage result. ### `nimbus-docs diff [file]` Read-only detail for starter files — what you changed, and what changed upstream: ```sh npx diff pnpm dlx diff yarn dlx diff bunx diff ``` ```sh npx diff src/components/ui/aside/Aside.astro pnpm dlx diff src/components/ui/aside/Aside.astro yarn dlx diff src/components/ui/aside/Aside.astro bunx diff src/components/ui/aside/Aside.astro ``` Each file is one of: **clean to pull** (upstream changed, you didn't), **added/removed upstream**, **hand-merge** (you both changed it), or **your changes** (you edited it, upstream didn't). For clean updates, additions, and removals, you can let the CLI apply one reviewed change: ```sh npx diff src/components/ui/aside/Aside.astro --apply pnpm dlx diff src/components/ui/aside/Aside.astro --apply yarn dlx diff src/components/ui/aside/Aside.astro --apply bunx diff src/components/ui/aside/Aside.astro --apply ``` `--apply` is explicit and per-file, rejects symlink/path escapes, and rechecks the clean preimage or absence before writing — it never merges. Review with `git diff` afterward. Pass `--to ` to target a specific tag, or `--template-dir ` to compare offline against a local checkout. ## `nimbus-docs lint` Walks `src/content/`, runs each authoring rule you've enabled, prints diagnostics, and exits non-zero when any `error`-severity finding survives. The build is never gated by lint — drafts that fail lint still render under `astro dev`. ```sh npx lint pnpm dlx lint yarn dlx lint bunx lint ``` Flags — combine with `lint`: | Flag | Effect | |---|---| | `--format=json` | agent-readable diagnostics | | `--rule=nimbus/single-h1` | run one rule only | | `--fix` | apply auto-fixes in place | | `--quiet` | errors only, suppress warnings | Severity overrides live with the integration (`nimbus(config, { rules })`); in-file disables (`nimbusDisableRules` frontmatter, inline comments) work with no config. ## Help and version ```sh npx --help pnpm dlx --help yarn dlx --help bunx --help ``` ```sh npx --version pnpm dlx --version yarn dlx --version bunx --version ``` Source: https://docs.klounge.kr/cli/index.mdx