init

Initialize project config and optionally install components. Supports templates and monorepo setup.

Usage

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

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

Creates duck-ui.config.json in the current directory and (optionally) seeds initial components.

Options

Flag	Description
`-y, --yes`	Skip prompts, use defaults
`-c, --cwd <cwd>`	Working directory
`-p, --project-type <type>`	Project type (`NEXT_JS`, `VITE`, `TANSTACK_START`, `UNKNOWN`)
`-b, --base-color <color>`	Base color for theme (any name from `theme list`)
`--alias <alias>`	Import alias root (default: `~`); components are written under `<alias>/ui`, `<alias>/libs`, `<alias>/hooks`, `<alias>/pages`, `<alias>/layouts`
`--css <path>`	Path to global CSS file (default: `./src/styles.css`)
`--css-variables` / `--no-css-variables`	Enable/disable CSS variables
`--no-monorepo`	Force single-project mode even when monorepo signals are detected
`-w, --workspace <path>`	Workspace where components are installed (implies monorepo)
`--css-workspace <path>`	Workspace that owns the CSS file (defaults to `--workspace`; implies monorepo)
`-t, --template <name>`	Scaffold from a project template
`--prefix <prefix>`	Tailwind class prefix (e.g. `tw-`); leave empty for none
`-a, --all`	Install all components

There is no standalone --monorepo flag. Monorepo mode is auto-detected (turbo/pnpm/nx/lerna/rush/package.json workspaces) and prompted for interactively; passing -w/--workspace or --css-workspace implies it, and --no-monorepo forces it off.

Examples

# Standard init: interactive prompts
npx @gentleduck/cli init

# Init with template scaffold
npx @gentleduck/cli init --template acme

# Init monorepo with an explicit workspace target
npx @gentleduck/cli init --workspace apps/web

# Init and install all components in one shot
npx @gentleduck/cli init --all -y

What it writes

A new duck-ui.config.json at the project root (or --cwd/--workspace):

{
  "schema": "https://gentleduck.org/schema.json",
  "rsc": true,
  "monorepo": false,
  "workspace": { "root": ".", "project": "." },
  "tailwind": {
    "baseColor": "zinc",
    "css": "./src/styles.css",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "ui": "~/ui",
    "libs": "~/libs",
    "hooks": "~/hooks",
    "pages": "~/pages",
    "layouts": "~/layouts"
  }
}

rsc is derived from --project-type: true only for NEXT_JS. Plus the generated theme CSS (light/dark tokens under a Tailwind v4 @theme inline block) written to the tailwind.css path.

Notes

TypeScript is required: declining the "install TypeScript?" prompt aborts init entirely (unless TypeScript is already installed, or -y/--yes is passed, which always installs it). There's no JS-output mode.
Tailwind required: components ship with Tailwind classes. Vanilla CSS is not currently a supported output mode.
Aliases are fixed suffixes, not tsconfig-derived: init writes <alias>/ui, <alias>/libs, etc. from whatever you type for --alias (default ~) - it doesn't read your tsconfig.json. Later commands (add/update/...) resolve that alias against your tsconfig.json's compilerOptions.paths to find where on disk to write files.