Marigold CLI

The @marigold/cli package brings the Marigold documentation into your terminal: fetch component docs, discover components and pages, scaffold Marigold into an existing project, and more. It's useful on its own and is built to ground AI coding agents on the canonical component API.

Installation

Install the CLI globally with npm or pnpm, or run it one-off with npx:

npm install -g @marigold/cli

pnpm add -g @marigold/cli

npx @marigold/cli docs Button

Usage with AI agents

AI coding agents are the CLI's primary audience. When invoked by an agent, prefer --format json together with --section props to get a structured, precise payload instead of formatted markdown:

# Structured prop data (recommended for AI agents)
marigold docs Select --section props --format json

# Discover components before writing code
marigold list --category form
marigold list --search date

To adopt a whole feature pattern rather than a single component, use marigold examples to discover and retrieve application-level patterns, then read the framework-transformation note once:

marigold examples list
marigold examples get filter --format json
marigold docs getting-started/examples-for-agents

When components render unstyled or throw, run marigold doctor --format json to diagnose the project's setup (packages, versions, provider, theme, Tailwind, React peer deps) and apply the returned suggestion for each issue:

marigold doctor --format json

The CLI detects common agent runtimes (Claude Code, Cursor, VS Code agent mode, Codex, or a generic AI_AGENT=1) via environment variables. For the full set of connection options (the MCP server and the public manifest / markdown endpoints), see Usage with AI.

Commands

marigold docs

Fetch and print the documentation for a component or a docs page.

marigold docs Button
marigold docs button --section props
marigold docs TextField --section props --format json
marigold docs select --format plain
marigold docs foundations/spacing
marigold docs getting-started/installation

A request like marigold docs Badge --section props prints a focused, terminal-rendered view of just that section:

Props

Badge

 | Prop     | Type      | Default | Description               |
 | :------- | :-------- | :------ | :------------------------ |
 | children | ReactNode | -       | Children of the component |

Pass a component name (case-insensitive, so Button, button, and BUTTON all resolve to the same component) or the slug of a non-component docs page (e.g. foundations/spacing, getting-started/installation). The props section is component-only. Requesting it for a page emits a note instead.

marigold list

List all available components and docs pages.

marigold list
marigold list --category form
marigold list --category foundations
marigold list --search date
marigold list --format json
marigold list --fresh

Components and pages are grouped by category. For example, marigold list --category form prints:

Form
  Autocomplete — A searchfield that displays a dynamic list of suggestions.
  Calendar — A date selection interface for choosing dates from a calendar view.
  Checkbox — Component to select one or more options.
  ComboBox — A text-field that allows the user to select values from a provided items array.
  …
  TextField — Component for input forms.
  TimeField — Component for entering time in forms.

marigold examples

Browse application-level reference patterns: multi-file compositions that show how Marigold components combine into real features (filterable tables, multi-section forms, component inventories). For how to adapt one to your own framework, see Adapting examples for agents.

marigold examples list                    # all available patterns
marigold examples get filter              # one pattern's source + metadata
marigold examples get filter --format json

Subcommands:

• list: print every available example (slug, title, brief, mapped patterns)
• get <slug>: fetch a single example: its source files, the canonical pattern docs it maps to, the mock-data shapes it depends on, which files are load-bearing vs. framework scaffolding, and its peer dependencies

marigold init

Interactive wizard to set up Marigold in an existing project.

marigold init
marigold init --yes             # skip prompts, accept Tailwind + package install
marigold init --skip-install    # apply config edits without running the install

It detects Next.js or Vite, then:

1. Installs @marigold/components, @marigold/system, @marigold/theme-rui, plus Tailwind v4 and the framework adapter (@tailwindcss/postcss for Next.js, @tailwindcss/vite for Vite) if Tailwind isn't already present. The Tailwind install is gated behind a confirmation prompt unless --yes is passed.
2. Patches your global CSS (app/globals.css, src/app/globals.css, src/index.css, or styles/globals.css) with the required @import and @source lines, preserving existing rules.
3. Patches vite.config.ts (Vite) or writes postcss.config.mjs (Next.js) if missing.
4. Wraps the root: creates app/providers.tsx and wraps {children} in app/layout.tsx (Next.js), or wraps <App /> in src/main.tsx (Vite).

marigold doctor

Diagnose why Marigold isn't working in a project and print a checklist with actionable fixes, ideal when components render unstyled or throw, and for AI agents to self-diagnose and repair a setup. All checks read the filesystem only; the freshness check additionally makes a short, best-effort fetch of the docs manifest (skipped with --offline).

marigold doctor                 # run from your project root
marigold doctor --format json   # structured report for AI agents / CI
marigold doctor --offline       # skip the network; freshness uses the cache only

It checks, against the current working directory:

1. Packages installed — @marigold/components, @marigold/system, and a theme (@marigold/theme-rui) are declared.
2. Package versions aligned — installed @marigold/components and @marigold/system match (they are released together).
3. Up to date — installed versions are the latest published (best-effort; skipped when offline).
4. MarigoldProvider wraps the app — the root layout wraps the app in <MarigoldProvider>.
5. Theme passed to MarigoldProvider — a theme prop is passed to the provider.
6. Tailwind configured for Marigold — the CSS entry imports tailwindcss and @marigold/theme-rui/theme.css, declares @source for node_modules/@marigold, and the framework build plugin is wired up.
7. React version compatible — installed React satisfies @marigold/components's peer requirement.

marigold migrate

Apply codemods for a breaking Marigold release, to your theme files and your application code. Run it after upgrading @marigold/components, from your project root.

marigold migrate v18                          # migrate the current directory
marigold migrate v18 ./src --dry-run          # report what would change, write nothing
marigold migrate                              # detect the installed version and confirm
marigold migrate v18 --only rename-imports    # apply a subset, non-interactively

Both positionals are optional. Without a version, the installed @marigold/components is detected and the applicable migration is proposed for confirmation. Without a path, the current directory is used.

It anchors on imports rather than on file names or directory layout, so it works whatever your project structure is:

1. Theme files (anchored on ThemeComponent<'X'> from @marigold/system): restructures single-style components into the slot shape the new version requires, moving your classes verbatim, swaps a baseline style only when it still matches the old baseline byte for byte (proof you never customized it), stubs new slots as cva({}), and scaffolds theme files for components the new version requires.
2. Application code (anchored on @marigold/components and @marigold/icons): renamed exports such as the icon migration, renamed compound components, renamed and removed props.
3. Design tokens: report-only, since token values are yours. Covers renamed or removed tokens you still reference, new tokens that component internals hardcode but your CSS does not define, and tokens that kept their name but changed meaning.

Anything that cannot be decided from the source, a spread that hides slots, a customized style, a DOM change your own CSS may target, becomes a warning pointing at the release notes, never a guess.

marigold completion

Print a tab-completion script for bash, zsh, or fish. Source it once per shell, or write it to your shell's completion directory for persistence.

# bash: current shell
source <(marigold completion bash)

# bash: persistent (with bash-completion installed)
marigold completion bash > ~/.local/share/bash-completion/completions/marigold

# zsh: persistent (ensure $fpath includes the dir, then run compinit)
marigold completion zsh > "${fpath[1]}/_marigold"

# fish
marigold completion fish > ~/.config/fish/completions/marigold.fish

Tab-completes subcommands, flag names, enum values (e.g. --format markdown|json|plain), categories (marigold list --category <TAB>), and component names (marigold docs <TAB>). Component and category suggestions are sourced from the local manifest cache. Run marigold list once to warm it.

marigold telemetry

Opt in or out of anonymous usage telemetry.

marigold telemetry status
marigold telemetry disable
marigold telemetry enable

Telemetry is on by default and carries no identifier — no account, user, machine, or session ID. Nothing links one command to another or to you, so there is no usage history to build, export, or hand over. Events are sent fire-and-forget from a detached background process, so telemetry never blocks your command, delays output, or surfaces a network error.

What is sent

One event per command invocation, with these fields and nothing else:

args keeps only flag presence and values from a closed set. Enum flags (--format, --section, --limit) are recorded as their validated value, or as invalid if unrecognised, so a typo is never echoed back. Identifier-shaped positionals (a component name, an example slug, a --category) are recorded only when they look like an identifier. Free-text is never sent — a marigold search query or a list --search term is recorded as used, so we learn that search was used but not what you searched for.

receivedAt is deliberately hour-granular: exact timestamps would let separate events be stitched back into a per-session sequence by timing alone, undoing the point of having no identifier.

What is never sent

• Your source code, file contents, file paths, or project names
• Search queries and any other free-form text you type
• Your name, email, username, hostname, or any account data
• Any persistent identifier, of any kind
• Your IP address is not stored. It's necessarily visible to our host in transit, as with any HTTP request, but it is never written into a telemetry record.

Events are deleted after 90 days, which covers release-over-release comparison, the longest window we analyse.

Why it's opt-out

Because there's nothing to consent to storing. We removed the per-machine identifier the CLI used to send, which means we can count invocations, not people — unique-user numbers come from public npm download counts instead. In exchange, the data stops being personal data, the CLI stops writing an identifier onto your device, and no per-user history exists to secure or hand over. An opt-in prompt would also be close to meaningless here: most runs are non-interactive, driven by AI agents in pipelines where no human is at a prompt to ask.

Turning it off

marigold telemetry disable persists the preference for the machine. Per-invocation, either env var works:

MARIGOLD_TELEMETRY_DISABLED=1 marigold docs Button
DO_NOT_TRACK=1 marigold docs Button

DO_NOT_TRACK follows the consoledonottrack.com convention, so setting it once opts you out of every tool that honours it. Telemetry is also suppressed automatically, with no configuration, when CI is detected (via ci-info, covering GitHub Actions, GitLab CI, CircleCI, etc.).

Global flags

Configuration

Every variable below is optional, the CLI works out of the box. Set one only to override a default (e.g. point at a self-hosted docs site, change the cache TTL, or opt out of telemetry).

Default cache and config locations: