CLI

Scaffold a new project, add components one at a time, and pick a type scale — without leaving the terminal. Five commands, no required flags, no global install.

Overview

The RenDS CLI is a single Node script (cli/index.js) shipped inside the design system folder. It exposes seven commands:

ren10 init

Scaffold tokens + base into a new rends/ folder.

ren10 add <name>

Copy a component (or all components) into your project.

ren10 remove <name>

Delete a previously-added component. Refuses if locally edited (use --force).

ren10 upgrade [name]

Refresh installed components from the package source. Diffs each file, prompts.

ren10 list

Print every component grouped by tier.

ren10 scales

Print every type scale ratio (minor-third, golden, …).

ren10 help

Show usage. --version prints the current release.

Copy, don't import. The CLI follows the shadcn/ui model — it copies source files into your project. You own the code, edit it freely, and aren't tied to a package version. There is no runtime dependency on the CLI after files land.

Install & run

The CLI lives inside the RenDS source tree. There are three equivalent ways to invoke it depending on how you got the code:

From a cloned repo

node rends/cli/index.js <command>

Via npm script (recommended in your `package.json`)

{
  "scripts": {
    "rends": "node rends/cli/index.js"
  }
}

Then call: npm run rends -- add button (the -- forwards args to the script).

From npm

The published package exposes the ren10 binary. Run it with npx or install it globally if you prefer a persistent shortcut:

npx ren10 --version
npx ren10 init
npx ren10 add button

Node 18+ required. The CLI uses ES modules (import), fileURLToPath, and modern fs APIs. Any current LTS is fine.

`init`

Scaffolds the foundation of a RenDS project: a fresh rends/ folder containing tokens, base styles, an empty components/ directory with an index.css ready to receive imports, and a top-level index.css that wires it all together.

node rends/cli/index.js init

terminal output

✓ Created rends/tokens/ ✓ Created rends/base/ ✓ Created rends/components/ ✓ Created rends/index.css Done! Add components with: node rends/cli/index.js add button node rends/cli/index.js add dialog node rends/cli/index.js add --all

Result on disk

my-project/ └── rends/ ├── index.css ← @imports tokens, base, components ├── tokens/ ← primitives + semantic + component layers ├── base/ ← reset, layouts, utilities └── components/ └── index.css ← empty, ready for `add`

Options

Flag	Default	Description
`--scale <ratio>`	`major-third`	Regenerate `typography.css` with a modular scale. See scales for the full list.
`--base <px>`	`16`	Base font size in pixels. Every step in the scale is computed from this anchor.
`--fluid`	off	Wrap each step in `clamp()` so type scales smoothly between viewport widths.
`--density <v>`	(none)	`comfortable` \| `compact` \| `spacious`. Doesn't modify CSS — prints the `data-density` attribute to add to your `<html>` element. The matching presets are already in `themes/appearance.css`.
`--shape <v>`	(none)	`rounded` \| `sharp` \| `pill`. Same idea: prints the `data-shape` attribute to add to `<html>`.

Examples

# Defaults: major-third, 16px base, no fluid scaling
node rends/cli/index.js init

# Tighter scale, larger anchor
node rends/cli/index.js init --scale minor-third --base 18

# Fluid responsive type
node rends/cli/index.js init --scale perfect-fourth --fluid

# Density + shape (prints the attrs to add to )
node rends/cli/index.js init --density compact --shape sharp

Refuses to overwrite. If rends/ already exists in the current directory, init exits with an error rather than clobber your work. Delete or rename the folder first.

`add`

Copies one component (or all of them) from the source registry into rends/components/<name>/, pulls in any utility dependencies, and updates components/index.css with the import line. Idempotent at the component level — re-adding throws rather than silently overwriting.

Add a single component

node rends/cli/index.js add button

terminal output

✓ Copied ren-button.css ✓ Copied ren-button.js ✓ Updated components/index.css Usage: <ren-button>Click me</ren-button> <ren-button variant="primary">Primary</ren-button> <ren-button variant="secondary" size="sm">Cancel</ren-button>

Add everything

node rends/cli/index.js add --all

Copies every primitive, composite, and pattern. Components that already exist are skipped (a count is reported at the end).

What gets copied

Each component ships as a self-contained folder. For ren-field for example:

rends/components/field/ ├── ren-field.css └── ren-field.js rends/utils/ └── id-generator.js ← pulled in as a dependency

Dependencies in rends/utils/ are shared across components. The CLI deduplicates — utilities already present are left alone with an ℹ already exists notice.

Wiring it up

After add, your components/index.css looks like:

/* RenDS — Components Layer */

@import './button/ren-button.css';
@import './field/ren-field.css';
@import './dialog/ren-dialog.css';

For interactive components, also load the JS module:

<script type="module" src="rends/components/dialog/ren-dialog.js"></script>

Unknown component? The CLI prints the error and points you at ren10 list for the canonical name list. Names are normalised to lowercase, so add Button works the same as add button.

`remove`

Deletes a component you previously installed, scrubbing both the directory under rends/components/<name>/ and the matching @import line in components/index.css. Alias: rm.

Basic use

node rends/cli/index.js remove tooltip
node rends/cli/index.js remove badge tag separator

Override protection

If remove detects that you've added extra files to the component folder, or that any tracked file has been modified vs the package source, it refuses to delete and reports what it found. This protects local customisations from accidental loss.

terminal output (override detected)

ℹ Skipped "dialog" — local overrides detected (modified file(s): ren-dialog.css). Re-run with --force to remove anyway.

Pass --force (or -f) to remove anyway:

node rends/cli/index.js remove dialog --force

What it does NOT do. remove doesn't touch rends/utils/ dependencies that the removed component may have pulled in. Shared utilities stay around in case another component relies on them. If you want a clean sweep, audit utils/ manually.

`upgrade`

Compares each installed component against the package source and prompts to overwrite files that differ. No arg = walk every installed component. With a name (or several), upgrade only those. Alias: update.

Basic use

# Upgrade everything that has drifted
node rends/cli/index.js upgrade

# Upgrade a specific component
node rends/cli/index.js upgrade dialog

# Preview what would change without writing
node rends/cli/index.js upgrade --dry-run

# CI mode — overwrite without prompting
node rends/cli/index.js upgrade --force

Interactive prompt

For each component that has any differing file, the CLI prints the list and asks:

dialog — 2 file(s) differ ~ ren-dialog.css ~ ren-dialog.js Overwrite 2 file(s) in dialog? [y]es / [n]o / [d]iff / [a]bort:

y — overwrite all differing files for this component.
n — leave this component alone and continue with the next.
d — print a minimal diff (red = local, green = upstream), then ask again.
a — abort the whole upgrade run; nothing written from here on.

Identical files are silent

If every tracked file matches the source, the component prints nothing — only the summary tells you it was up to date. This keeps upgrade noiseless when you run it after a small package bump.

Bring your overrides back. upgrade overwrites local edits when you accept. If you want to keep yours and also pick up upstream changes, run upgrade --dry-run first, then merge by hand.

`list`

Prints every component the CLI knows about, grouped by tier and annotated with a one-line description. Use it to discover what's available and to look up canonical names before add.

node rends/cli/index.js list

terminal output (excerpt)

RenDS Components (52) PRIMITIVES button Versatile button with variants, sizes, icon support, loading state field Form field wrapper with label, error, description checkbox Checkbox and toggle switch with accessibility badge Status badge with semantic colors … 14 more COMPOSITES dialog Modal dialog with focus trap and Escape handling select Accessible custom select with keyboard nav combobox Filterable select with autocomplete … 23 more PATTERNS nav Top navigation bar with responsive collapse sidebar Collapsible sidebar with grouped sections form Composed form pattern: fields + validation + submit … 5 more

`scales`

Lists the modular type scale ratios you can pass to init --scale. Three are marked ★ as recommended for web; the default is major-third.

node rends/cli/index.js scales

terminal output

Available Type Scale Ratios Use with: node rends/cli/index.js init --scale <ratio> minor-second Minor Second (1.067) major-second Major Second (1.125) minor-third Minor Third (1.200) ★ major-third Major Third (1.250) ★ ← default perfect-fourth Perfect Fourth (1.333) ★ augmented-fourth Aug. Fourth (1.414) perfect-fifth Perfect Fifth (1.500) golden Golden Ratio (1.618) ★ = recommended for web

Picking a ratio

minor-third (1.200) — dense UIs, dashboards, data-heavy apps.
major-third (1.250) — balanced default. Works for most product UIs.
perfect-fourth (1.333) — editorial / marketing pages with display headlines.
golden (1.618) — high-impact landing pages where headers should dominate.

Rule of thumb: smaller ratios for information-dense screens, larger for narrative content.

Workflows

Greenfield project — minimal

node rends/cli/index.js init
node rends/cli/index.js add button
node rends/cli/index.js add field
node rends/cli/index.js add dialog

Three components is enough for an auth screen, a settings panel, and most CRUD flows.

Greenfield project — kitchen sink

node rends/cli/index.js init --scale perfect-fourth --fluid
node rends/cli/index.js add --all

Every component, fluid responsive type, no decisions to defer.

Adding to an existing RenDS project

add is safe to run incrementally. Each call only touches the named component's folder and appends to components/index.css. Re-running add button on a folder that already has it errors out — delete first if you want to re-pull.

Custom theme on top

The CLI doesn't generate themes. Use the Theme Builder instead, or hand-edit themes/appearance.css. The CLI only owns the structural scaffold (tokens + base + components).

Troubleshooting

`rends/ directory already exists`

You ran init in a folder that already has a rends/ child. Move or delete it, then re-run. There is no --force flag by design — clobbering a token folder is rarely what you want.

`Unknown component: foo`

The name doesn't match the registry. Run list to see canonical names. Common slips: buttons (singular only), modal (it's dialog), dropdown (it's menu or combobox depending on what you want).

`Component "X" already exists`

add refuses to overwrite. Either you've already added it (check components/index.css) or there's a stale folder. Delete rends/components/X/ and re-run.

`Unknown scale ratio: "X"`

The ratio name isn't in the catalog. Run scales for the list. Names are kebab-case: perfect-fourth, not perfectFourth or perfect_fourth.

Command runs but nothing happens

Check Node version: the CLI requires Node 18+ for ES module support. node --version. Older Node will silently fail on the import at the top of index.js.

Next steps

You've scaffolded a project and pulled components. Where to go from here:

Setup

Getting Started

From an empty folder to a styled, accessible page in two minutes.

Foundations

Tokens reference

Every value in the three-tier system: primitives, semantic, component.

Catalog

Components showcase

Live examples of every component you can add.

Tool

Theme Builder

Generate a custom theme, export as CSS / JSON / ZIP, share via URL.

CLI

Overview

Install & run

From a cloned repo

Via npm script (recommended in your package.json)

From npm

init

Result on disk

Options

Examples

add

Add a single component

Add everything

What gets copied

Wiring it up

remove

Basic use

Override protection

upgrade

Basic use

Interactive prompt

Identical files are silent

list

scales

Picking a ratio

Workflows

Greenfield project — minimal

Greenfield project — kitchen sink

Adding to an existing RenDS project

Custom theme on top

Troubleshooting

rends/ directory already exists

Unknown component: foo

Component "X" already exists

Unknown scale ratio: "X"

Command runs but nothing happens

Next steps

Via npm script (recommended in your `package.json`)

`init`

`add`

`remove`

`upgrade`

`list`

`scales`

`rends/ directory already exists`

`Unknown component: foo`

`Component "X" already exists`

`Unknown scale ratio: "X"`