Skip to main content
Search...

gentleduck/cli

Use the gentleduck CLI package to initialize configs and install components from the registry.

Loading diagram...

Philosophy

gentleduck/cli copies source files into your project instead of installing pre-built UI packages. You keep full ownership of the code and can customize immediately.

Commands

init

Initialize project config and optionally install components.

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

Options:

  • -y, --yes
  • -c, --cwd <cwd>
  • -p, --project-type <type>
  • -b, --base-color <color>
  • --alias <alias>
  • --css <path>
  • --css-variables
  • --no-css-variables
  • --monorepo
  • --no-monorepo
  • -w, --workspace <path>
  • --prefix <prefix>
  • -a, --all

add

Install components from the registry.

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

Options:

  • -y, --yes
  • -f, --force
  • -c, --cwd <cwd>
  • -w, --workspace <path>
  • -a, --all

update

Update installed local components to latest registry versions.

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

Options:

  • -a, --all
  • -y, --yes
  • -c, --cwd <cwd>
  • -w, --workspace <path>

remove

Remove installed local components.

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

Options:

  • -y, --yes
  • -c, --cwd <cwd>
  • -w, --workspace <path>

diff

Show differences between installed components and registry versions.

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

Options:

  • -c, --cwd <cwd>
  • -g, --gui
  • -w, --workspace <path>

list

List available components from the registry.

npx @gentleduck/cli list
npx @gentleduck/cli list

Options:

  • -t, --type <type> - filter by component type (e.g. ui, hook, lib, block)
  • -j, --json - output as JSON

Examples:

# List all available components
npx @gentleduck/cli list
 
# List only UI components
npx @gentleduck/cli list --type ui
 
# Output the full list as JSON
npx @gentleduck/cli list --json
# List all available components
npx @gentleduck/cli list
 
# List only UI components
npx @gentleduck/cli list --type ui
 
# Output the full list as JSON
npx @gentleduck/cli list --json

Monorepo Usage

When duck-ui.config.json has "monorepo": true, the CLI resolves the install target from:

  1. duck-ui.config.json workspace field
  2. --workspace override (if provided)

The CLI validates that the target workspace has:

  • package.json
  • tsconfig.json (for component commands)

If --workspace is not provided and you run a command inside a workspace directory, the CLI infers the target from the nearest parent package.json.

Example

npx @gentleduck/cli add button --workspace apps/web
npx @gentleduck/cli add button --workspace apps/web

Init with explicit workspace

npx @gentleduck/cli init --monorepo --workspace apps/web
npx @gentleduck/cli init --monorepo --workspace apps/web

Migration Note

Legacy duck-ui.config.json files (without workspace) are rejected. Re-run init to migrate:

npx @gentleduck/cli init
npx @gentleduck/cli init
2024Overview