cli.mdx

title	CLI
description	The nimbus-docs CLI — list what's available, add it to your project, lint your content.
sidebar	order 2

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.

Filter by type:

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.

Walks the slug's `registryDependencies` and any npm `dependencies` it needs. Drops each file into the right path under `src/components/ui/`, `src/lib/`, or wherever the entry declares. 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:

--yes assents to prompts (e.g. dependency installs) without touching existing files — so it's safe in CI. 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.

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:

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.

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 runbook so the agent can safely adapt project-owned or split configuration. From a regular shell, use --print to request that runbook explicitly:

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.

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 and templates-v* tag can't be recovered from the repo alone, so they're left blank (and flagged reconstructed) for you to fill in if you know them.

Keeping up to date

You own your files, so upgrades are opt-in — nothing changes under you. Two commands, one for each tier:

nimbus-docs outdated

The read-only "am I behind?" check, across both tiers:

• Registry components — compares each recorded content hash against the current registry; run add <slug> --overwrite to update.
• Starter files — compares your scaffolded files against the upstream templates-v* tag. 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).

nimbus-docs diff [file]

Read-only detail for starter files — what you changed, and what changed upstream:

Each file is one of: clean to pull (upstream changed, you didn't), hand-merge (you both changed it), or your changes (you edited it, upstream didn't). For a clean file you can let the CLI write the upstream version:

--apply is explicit and per-file, and refuses anything you've edited — it only pulls clean upstream changes, 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.

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