## Usage

```bash
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

| Flag | Description |
| --- | --- |
| `-y, --yes` | Skip confirmation prompts |
| `-f, --force` | Overwrite existing files |
| `-c, --cwd <cwd>` | Working directory |
| `-w, --workspace <path>` | Target workspace |
| `-a, --all` | Install all components |

***

## Examples

```bash
# 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 (`@/components`, `@/hooks`, `@/lib`).

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

***

## Notes

* **No version drift** — your component is now your source. The registry won't push silent changes.
* **Diff to track upstream** — see [`diff`](/duck-cli/commands/diff) to compare your copy against the latest registry version.
* **Update with merge** — see [`update`](/duck-cli/commands/update) to pull upstream changes via the interactive merge TUI.