Skip to content
Nimbus

CLI

Every nimbus-docs command, with its flags and what it changes.

Updated

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.

Command What it does
list Lists what the registry has.
add <slug> Installs a component, utility, feature or server adapter.
add source <name|url> Hands your coding agent a guide for a content source.
init Writes nimbus.json for a project that lacks one.
migrate Applies package API migrations and lists upgrade reviews.
outdated Lists starter files, components and package API work that changed upstream.
diff [file] Shows, or takes, the upstream change to a starter file.
check Checks the project’s setup, config and content without a build.
lint Runs the authoring rules you’ve turned on.

nimbus-docs list

Lists every installable component, utility, feature and content source.

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
npx @cloudflare/nimbus-docs list --type source

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

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

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,” 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 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.

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

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.

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

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:

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 add source <name|url>

Adds a content source: part of the site built from another git repository, a Notion database, or any provider. See Content from other sources.

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

These commands keep a site current. Upgrade Nimbus 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:

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

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:

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

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

npx @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 <templates-vX.Y.Z> compares against a specific tag, and --template-dir <path> 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:

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

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. It exits non-zero when an error finding remains. Lint never blocks the build.

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

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

npx @cloudflare/nimbus-docs --help
npx @cloudflare/nimbus-docs --version
Edit this page
Nimbus

Type to search…

↑↓ navigate↵ selectEsc close