gentleeduck/duck-ui / skills/duck-cli
duck-cli
VerifiedUse when working with @gentleduck/cli - the command-line tool for initializing projects, scaffolding from templates, and adding components. Covers the init, add, update, remove, diff, and list commands.
@gentleduck/cli
You are an expert on the duck-ui CLI tool. Your scope is packages/duck-cli/. This package provides the npx @gentleduck/cli command that helps users bootstrap projects and install components.
Global Flag
--verbose - show detailed error output (stack traces). Handled via a preAction hook in src/main/main.ts.
Commands
init
Initializes a project with duck-ui configuration.
npx @gentleduck/cli init # Interactive
npx @gentleduck/cli init -y # Non-interactive with defaults
npx @gentleduck/cli init --template acme --cwd ./app # Scaffold from template
npx @gentleduck/cli init --monorepo -w packages/ui # Monorepo workspace
npx @gentleduck/cli init -p NEXT_JS -b zinc --css ./src/styles.css
npx @gentleduck/cli init -a # Init and install all components
npx @gentleduck/cli init button dialog # Init and install specific components
Flags: -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, -t, --template <name>.
add
Adds components to an existing project.
npx @gentleduck/cli add button dialog tabs
npx @gentleduck/cli add -f # Overwrite existing
npx @gentleduck/cli add -w packages/ui # Monorepo workspace
npx @gentleduck/cli add -a # All components
npx @gentleduck/cli add -y # Skip prompts
Flags: -y, --yes, -f, --force, -c, --cwd <cwd>, -w, --workspace <path>, -a, --all.
update, remove, diff
npx @gentleduck/cli update button # Update component to latest
npx @gentleduck/cli remove button # Remove component
npx @gentleduck/cli diff button # Show diff between local and registry
All three accept: -y, --yes, -c, --cwd <cwd>, -w, --workspace <path>.
list
npx @gentleduck/cli list # List available components
npx @gentleduck/cli list -t ui # Filter by type (ui, hook, lib, block)
npx @gentleduck/cli list -j # Output as JSON
Flags: -t, --type <type>, -j, --json.
Source Structure
packages/duck-cli/src/
├── commands/{name}/ # 5 files each: .ts, .libs.ts, .dto.ts, .constants.ts, .types.ts
│ └── shared.types.ts # CommandConfig, OptionType (re-exported by each .types.ts)
├── utils/ # template-scaffold/, get-package-manager/, get-project-info/,
│ # preflight-configs/, registry-mutation/, get-registry/,
│ # text-styling/, diff-format/, merge/, workspace/,
│ # resolve-components.ts, spinner.ts, banner.ts, verbose.ts,
│ # require-config-value.ts
├── main/ # main.ts (commander setup), main.constants.ts (REGISTRY_URL)
├── gui/ # ink-based interactive UI
└── index.ts # entry point
Command Pattern
Each command has five files. See COMMAND-PATTERN.md for the full pattern with code examples.
Registry API
The registry URL defaults to https://gentleduck.org/duck-ui/r and can be overridden with the COMPONENTS_REGISTRY_URL env var. Defined in src/main/main.constants.ts as REGISTRY_URL.
Local Development
cd packages/duck-cli
bun run build # Build with tsdown into dist/index.mjs
bun run dev # Watch mode
bun run start -- init -y # Run the built CLI
bun run start:dev -- init -y # Run against local registry (localhost:3003)
bun run test # Run vitest
Error Patterns
- Command not found -- forgot to register in
src/main/main.ts - Option type mismatch -- Zod schema field name/type does not match the Commander option
- Registry fetch failure -- check
get-registry/and theCOMPONENTS_REGISTRY_URLenv var - Template not found -- tarball filter pattern does not match the template directory name
Do Not
- Do not run arbitrary shell commands -- use
execawith explicit command and args arrays - Do not skip Zod validation -- always parse options through the schema before use
- Do not use
console.logfor user feedback -- use thespinnerandhighlighterutilities - Do not hardcode registry URLs -- use
REGISTRY_URLfrommain.constants.ts - Do not add commands without updating the snapshot test at
src/__test__/unit/command-help.test.ts
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |