--- title: "CLI" description: "Every nimbus-docs command, with its flags and what it changes." --- > Documentation Index > Fetch the complete documentation index at: https://nimbus-docs.com/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. | Command | What it does | | --- | --- | | [`list`](#nimbus-docs-list) | Lists what the registry has. | | [`add `](#nimbus-docs-add-slug) | Installs a component, utility, feature or server adapter. | | [`add source `](#nimbus-docs-add-source-nameurl) | Hands your coding agent a guide for a content source. | | [`init`](#nimbus-docs-init) | Writes `nimbus.json` for a project that lacks one. | | [`migrate`](#nimbus-docs-migrate) | Applies package API migrations and lists upgrade reviews. | | [`outdated`](#nimbus-docs-outdated) | Lists starter files, components and package API work that changed upstream. | | [`diff [file]`](#nimbus-docs-diff-file) | Shows, or takes, the upstream change to a starter file. | | [`check`](#nimbus-docs-check) | Checks the project's setup, config and content without a build. | | [`lint`](#nimbus-docs-lint) | Runs the authoring rules you've turned on. | ## `nimbus-docs list` Lists every installable component, utility, feature and content source. ```sh npx @cloudflare/nimbus-docs list yarn nimbus-docs list pnpm nimbus-docs list bunx @cloudflare/nimbus-docs list ``` Filter by type: ```sh npx @cloudflare/nimbus-docs list --type ui yarn nimbus-docs list --type ui pnpm nimbus-docs list --type ui bunx @cloudflare/nimbus-docs list --type ui ``` ```sh npx @cloudflare/nimbus-docs list --type lib yarn nimbus-docs list --type lib pnpm nimbus-docs list --type lib bunx @cloudflare/nimbus-docs list --type lib ``` ```sh npx @cloudflare/nimbus-docs list --type feature yarn nimbus-docs list --type feature pnpm nimbus-docs list --type feature bunx @cloudflare/nimbus-docs list --type feature ``` ```sh npx @cloudflare/nimbus-docs list --type source yarn nimbus-docs list --type source pnpm nimbus-docs list --type source bunx @cloudflare/nimbus-docs list --type source ``` 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 @cloudflare/nimbus-docs add badge yarn nimbus-docs add badge pnpm nimbus-docs add badge bunx @cloudflare/nimbus-docs 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. #### Already installed `add` never overwrites files you own. It adds missing files, keeps files that differ from the registry, and lists both. A component that already matches the registry is reported as up to date. #### Replace your copy `--overwrite` replaces files that differ with the registry version, and lists each one. In a terminal, it asks first if you've edited the component or its dependencies. Without a terminal, such as an agent, CI or a pipe, edited components are kept, listed with the command that replaces them, and the command exits `1`. `--overwrite --yes` replaces them and says how many had edits. `add` finds your edits from the install record in `nimbus.json`. For a component that came with the starter, it compares against your starter release, downloaded from GitHub. If that download is rate-limited, set `GIGET_AUTH` to a GitHub token, or pass `--template-dir ` to use a local checkout. With neither, it asks in a terminal and otherwise keeps the files. Commit first, run it, and review the change with `git diff`: ```sh npx @cloudflare/nimbus-docs add badge --overwrite yarn nimbus-docs add badge --overwrite pnpm nimbus-docs add badge --overwrite bunx @cloudflare/nimbus-docs 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," and `--overwrite --yes` only when you've decided to discard your edits. Once installed, the component is yours to edit; there's no upstream API to break. Each `add` records it in [`nimbus.json`](/project-structure) with its slug, registry, release and a content hash, so upgrades can tell what you changed. ### 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 @cloudflare/nimbus-docs add 404-page yarn nimbus-docs add 404-page pnpm nimbus-docs add 404-page bunx @cloudflare/nimbus-docs 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 @cloudflare/nimbus-docs add 404-page --print | claude yarn nimbus-docs add 404-page --print | claude pnpm nimbus-docs add 404-page --print | claude bunx @cloudflare/nimbus-docs add 404-page --print | claude ``` ```sh npx @cloudflare/nimbus-docs add 404-page --print | codex yarn nimbus-docs add 404-page --print | codex pnpm nimbus-docs add 404-page --print | codex bunx @cloudflare/nimbus-docs add 404-page --print | codex ``` Use `--print` to force the markdown output, skipping detection. ### Server adapters Add the adapter for the host you deploy to: `adapter-cloudflare`, `adapter-netlify`, `adapter-node` or `adapter-vercel`. 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 @cloudflare/nimbus-docs add adapter-cloudflare yarn nimbus-docs add adapter-cloudflare pnpm nimbus-docs add adapter-cloudflare bunx @cloudflare/nimbus-docs add adapter-cloudflare ``` `adapter-cloudflare` also does two things: - **Rendering policy.** It adds request rendering when the Nimbus config has none. An existing policy is kept, and an imported or ambiguous config gets a coding-agent handoff instead. - **`wrangler.jsonc`.** It writes a server-compatible one when none exists, or replaces an unchanged static one from Nimbus. A customized `wrangler.jsonc`, or a JSON or TOML config, is left alone. 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)], }); ``` A coding agent running an adapter command gets the same edits as a shell. Sometimes `adapter-cloudflare` can't edit the config safely: there's no marked `output` block, `output` isn't a literal, the config is CommonJS or a symlink, the write fails, or the Nimbus config is imported. It then says why, prints a recipe for your agent to finish the job, and exits `0`. `--print` prints that recipe without changing anything: ```sh npx @cloudflare/nimbus-docs add adapter-cloudflare --print | claude yarn nimbus-docs add adapter-cloudflare --print | claude pnpm nimbus-docs add adapter-cloudflare --print | claude bunx @cloudflare/nimbus-docs add adapter-cloudflare --print | claude ``` Always run the project’s production build afterward. See [Rendering policy](/reference/rendering) for per-collection build/request overrides. The equivalent long form is `nimbus-docs add server-output --adapter `. ## `nimbus-docs add source ` Adds a content source: part of the site built from another git repository, a Notion database, or any provider. See [Content from other sources](/content-sources/git). ```sh npx @cloudflare/nimbus-docs add source github --print | claude yarn nimbus-docs add source github --print | claude pnpm nimbus-docs add source github --print | claude bunx @cloudflare/nimbus-docs add source github --print | claude ``` | Name | Source | |---|---| | `git`, `github`, `gitlab`, `bitbucket` | Another git repository. The aliases print the same guide with the host's values. | | `notion` | A Notion database. The agent installs `@notionhq/client` and `notion-to-md` and writes `src/loaders/notion.ts`. | | a URL | A provider's documentation: a guide for writing its loader, starting from that URL. | `add source` alone lists them. Like a feature, the guide goes to your coding agent, and the agent writes any code the source needs; `add source` itself writes no files. A source's name on its own, such as `add notion`, points you to `add source notion`. ## `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 @cloudflare/nimbus-docs init yarn nimbus-docs init pnpm nimbus-docs init bunx @cloudflare/nimbus-docs 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 # scan a nested package (monorepo) npx @cloudflare/nimbus-docs init --root packages/docs yarn nimbus-docs init --root packages/docs pnpm nimbus-docs init --root packages/docs bunx @cloudflare/nimbus-docs init --root packages/docs ``` ```sh # rebuild an existing record npx @cloudflare/nimbus-docs init --force yarn nimbus-docs init --force pnpm nimbus-docs init --force bunx @cloudflare/nimbus-docs init --force ``` ## Keeping up to date These commands keep a site current. [Upgrade Nimbus](/publish/upgrading) puts them in order for a release. ### `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 nimbus-docs migrate --from PREVIOUS_VERSION ``` | Flag | Effect | |---|---| | `--dry-run`, `--diff` | Show the plan without changing files. | | `--yes --json` | Apply and report as JSON, for agents. | | `--print` | Print the remaining work as one Markdown handoff for an agent. | | `--src-dir ` | Name Astro's `srcDir` when the config computes it. | The output lists the version range, required reviews, planned diffs, blockers and errors. Files outside the reported scan aren't claimed as checked. Optional upgrade entries come after required work. They never stop a build, but read each one: some describe a change the release makes on its own, such as newly published files. `migrate --yes` records them as reviewed. After completing all reported work, explicitly confirm it and advance the committed reviewed baseline: ```sh pnpm nimbus-docs migrate --from PREVIOUS_VERSION --yes ``` Pass `--from` only when the project has no recorded baseline. In a terminal, `migrate` asks before recording the reviewed version in `nimbus.json`; without one, it records it only with `--yes`. It never records it while a migration remains. A pending required review also stops `astro dev`. With `astro dev --background`, the server only reports that it exited, so run `nimbus-docs check` to see which review. Next, run `outdated`, then `nimbus-docs check`, `astro check` and the production build. ### `nimbus-docs outdated` The read-only "am I behind?" overview across package APIs, starter files, and registry components: ```sh npx @cloudflare/nimbus-docs outdated yarn nimbus-docs outdated pnpm nimbus-docs outdated bunx @cloudflare/nimbus-docs outdated ``` - **Package APIs** — pending migrations and reviews, which `migrate` handles. It also says when a newer Nimbus release is on npm. Reviews about API reference pages are skipped when `src/content.config.*` clearly doesn't use `apiCollection`. - **Registry components** — components that changed upstream, and npm dependencies older than a component needs, with the command to update them. Updates stay review-only, because overwriting can change dependencies too. - **Starter files** — your `src/` files, `AGENT.md`, `CLAUDE.md` and `tsconfig.json`, compared with the upstream `templates-v*` tag. `git diff` can't show this, because that tag was never in your history. Content files are hidden unless you pass `--all`. Files every site rewrites, such as `package.json`, `wrangler.jsonc` and `nimbus.json`, aren't compared. `--json` gives agent-readable findings. `summary.packageApis` counts every migration and review, and `summary.requiredPackageApis` the required ones. A `starter-needs-newer-package` warning means the newer starter needs a newer package than you have, and it blocks `diff --apply`. Without a complete `nimbus.json`, you still get the package API results, marked as partial. ### `nimbus-docs diff [file]` Read-only detail for starter files — what you changed, and what changed upstream: ```sh # every changed starter file npx @cloudflare/nimbus-docs diff yarn nimbus-docs diff pnpm nimbus-docs diff bunx @cloudflare/nimbus-docs diff ``` ```sh # one file npx @cloudflare/nimbus-docs diff src/components/ui/aside/Aside.astro yarn nimbus-docs diff src/components/ui/aside/Aside.astro pnpm nimbus-docs diff src/components/ui/aside/Aside.astro bunx @cloudflare/nimbus-docs diff src/components/ui/aside/Aside.astro ``` | Status | Meaning | |---|---| | clean to pull | Upstream changed it; you didn't. | | added or removed upstream | The file is new upstream, or gone. | | hand-merge | You both changed it. | | your changes | You changed it; upstream didn't. Nothing to pull. | For a clean update, addition or removal, the CLI can apply the change for one file: ```sh npx @cloudflare/nimbus-docs diff src/components/ui/aside/Aside.astro --apply yarn nimbus-docs diff src/components/ui/aside/Aside.astro --apply pnpm nimbus-docs diff src/components/ui/aside/Aside.astro --apply bunx @cloudflare/nimbus-docs diff src/components/ui/aside/Aside.astro --apply ``` `--apply` works one file at a time and never merges: it rechecks that the file is still unedited, then writes. It records the tag in `nimbus.json` (`templatesTagByFile`), so later diffs start from there. Review with `git diff` afterward. Starter route files are compared in your site's rendering mode, so a route updated by `check --fix` doesn't show as your change. `--to ` compares against a specific tag, and `--template-dir ` against a local checkout. ## `nimbus-docs check` A build-free preflight. It checks the environment, project structure, pending migrations, authoring rules, and types, then reports whether the site can build: ```sh pnpm nimbus-docs check ``` Pass `--env`, `--structure`, `--migrations`, `--lint`, or `--types` to run only those categories. `--fix` applies the fixes it can make safely and asks before any fix that needs a value or installs a dependency. Without a terminal it skips the questions and installs only with `--yes`. `--quiet` shows errors only. `check` reports each route file Nimbus manages whose mode disagrees with [`rendering`](/reference/rendering) (`nimbus/route-file-mode`). Without `rendering`, that's building each of them ahead of time. `--fix` updates the file and lists every file it wrote. For a route it can't fully edit, it makes the changes it can and lists what's left. `--types` type-checks your `.ts` and `.tsx` files with your own TypeScript. It doesn't read `.astro` files; run `astro check` for those. `check` exits `1` when an error-severity finding remains, and `0` otherwise. Warnings, informational findings, and checks that couldn't run never change the exit code. Pass `--json` for agent-readable output. `status` is `passed`, `failed`, or `partial` (some checks couldn't run), and `readiness` is `buildable`, `blocked`, or `unknown`. Each finding has one of three severities: | Severity | Meaning | |---|---| | `error` | Must be fixed. Counted in `summary.errors` and sets the exit code to `1`. | | `warn` | Advisory, such as the placeholder `site` URL. Counted in `summary.warnings`. | | `info` | Informational only, such as an optional upgrade entry from `migrate`. Not counted in the summary. | Checks that couldn't run are listed as `notes` on their scope rather than as findings, each with the reason it was skipped. In the terminal, a scope with notes shows `◐ ok, partly checked`. `check` checks links only when an earlier `astro build` left `.nimbus/routes.json`; without it, link checking is a note, not an error. To gate CI on links, run `astro build` and then `nimbus-docs lint`; see [Check links](/writing/linting#check-links). ## `nimbus-docs lint` Runs the authoring rules you've turned on over `src/content/`, and over collections that load from elsewhere, such as [content sources](/content-sources/git). It exits non-zero when an `error` finding remains. Lint never blocks the build. ```sh npx @cloudflare/nimbus-docs lint yarn nimbus-docs lint pnpm nimbus-docs lint bunx @cloudflare/nimbus-docs 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 | You set rules in the integration (`nimbus(config, { rules })`), and `astro build`, `astro dev` or `astro sync` writes them to `.nimbus/lint.json`. Without that file, `lint` exits `1` and asks you to build first, unless `--rule` names a rule. If the rules changed since, it asks you to run `astro sync`. `nimbusDisableRules` frontmatter and inline comments turn rules off in one file, with no config. `nimbus/internal-link` and `nimbus/redirected-link` need `astro build` to run first. Without the route list the build writes, lint exits `1` with an error on `.nimbus/routes.json`. ## Help and version ```sh npx @cloudflare/nimbus-docs --help yarn nimbus-docs --help pnpm nimbus-docs --help bunx @cloudflare/nimbus-docs --help ``` ```sh npx @cloudflare/nimbus-docs --version yarn nimbus-docs --version pnpm nimbus-docs --version bunx @cloudflare/nimbus-docs --version ``` Source: https://nimbus-docs.com/cli/index.mdx