add

Usage

npx @gentleduck/cli add [components...]

npx @gentleduck/cli add [components...]

Components are copied as source files into your project. You own the code afterward: patch, restyle, extend without forking.

Options

Examples

# Add specific components
npx @gentleduck/cli add button dialog calendar

# Add all components
npx @gentleduck/cli add --all

# Add to a specific workspace
npx @gentleduck/cli add sidebar --workspace apps/dashboard

# Force overwrite of an existing copy
npx @gentleduck/cli add button --force

How it works

1. Resolves the component from the configured registry (https://gentleduck.org/r by default; override with COMPONENTS_REGISTRY_URL).
2. Walks dependency graph: installs registry-level dependencies (e.g. dialog pulls in button).
3. Installs npm dependencies: runs bun add / npm install for any external packages declared by the component.
4. Writes files to the configured aliases (<alias>/ui, <alias>/hooks, <alias>/libs, ... - see init).
5. Imports stylesheets: when a component ships a .css file (like typeset), the CLI adds an @import for it to your tailwind.css file, after the Tailwind import. Running add again never duplicates it.

If a target file already exists, the CLI asks before overwriting unless --force or --yes is set.

Only gentleduck.org is trusted by default. An https registry outside that host is refused unless you opt in with COMPONENTS_ALLOW_REGISTRY=<host>; overriding via COMPONENTS_REGISTRY_URL implicitly trusts that host too (with a one-time warning), but plain http is still refused except for a localhost override.

Notes

• No version drift: your component is now your source. The registry won't push silent changes.
• Diff to track upstream: see diff to compare your copy against the latest registry version.
• Update with merge: see update to pull upstream changes via the interactive merge TUI.