Skip to content
Nimbus

CLI

Use the nimbus-docs CLI to install registry features, migrate package APIs, review copied code, and check content.

Updated View as Markdown

The nimbus-docs CLI lists what’s in the registry, installs it, records what you own in nimbus.json, shows what’s fallen behind upstream, and lints your MDX content.

nimbus-docs list

Lists every installable component, utility, and feature.

npx @cloudflare/nimbus-docs list

Filter by type:

npx @cloudflare/nimbus-docs list --type ui
npx @cloudflare/nimbus-docs list --type lib
npx @cloudflare/nimbus-docs list --type feature

Running nimbus-docs add with no slug shows the same list.

nimbus-docs add <slug>

Registry entries use two install modes based on their type. Special adapter-<id> 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.

npx @cloudflare/nimbus-docs add badge

Resolve dependencies

Walks the slug’s registryDependencies and any npm dependencies it needs.

Copy files

Drops each file into the right path under src/components/ui/, src/lib/, or wherever the entry declares.

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:

npx @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.”

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 — 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.

npx @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:

npx @cloudflare/nimbus-docs add 404-page --print | claude
npx @cloudflare/nimbus-docs 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.

npx @cloudflare/nimbus-docs 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:

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:

npx @cloudflare/nimbus-docs add adapter-cloudflare --print | claude

Always run the project’s production build afterward. See Rendering policy for per-collection build/request overrides.

The equivalent long form is nimbus-docs add server-output --adapter <cloudflare|vercel|netlify|node>.

nimbus-docs init

Writes a nimbus.json 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.

npx @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 <version> to establish the upgrade range.

# scan a nested package (monorepo)
npx @cloudflare/nimbus-docs init --root packages/docs
# rebuild an existing record
npx @cloudflare/nimbus-docs init --force

Keeping up to date

Package managers update Nimbus itself; Nimbus updates known API usage and reviews copied code:

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:

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 <relative-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:

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:

npx @cloudflare/nimbus-docs 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:

# every changed starter file
npx @cloudflare/nimbus-docs diff
# one file
npx @cloudflare/nimbus-docs 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:

npx @cloudflare/nimbus-docs 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 <templates-vX.Y.Z> to target a specific tag, or --template-dir <path> 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.

npx @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

Severity overrides live with the integration (nimbus(config, { rules })); in-file disables (nimbusDisableRules frontmatter, inline comments) work with no config.

Help and version

npx @cloudflare/nimbus-docs --help
npx @cloudflare/nimbus-docs --version
Navigation

Type to search…

↑↓ navigate↵ selectEsc close