CLI

The Klean CLI installs and safely updates source in conventional Boring Stack applications:

npx klean-ui add button
npx klean-ui add input
npx klean-ui add textarea
npx klean-ui add select
npx klean-ui check
npx klean-ui diff button
npx klean-ui update button
npx klean-ui update --all

It has one job: keep the right framework-native source in the right application path without taking ownership away from the application.

How npx klean-ui add works

The published klean-ui npm package exposes a klean-ui executable. npx resolves and runs that executable for the command; it does not add Klean as an application runtime dependency.

The CLI performs a deterministic pipeline:

1. Locate the application root. Walk upward to the Sails package.json.
2. Detect the framework. Inspect dependencies and the conventional frontend entry for reliable Vue, React, or Svelte evidence.
3. Resolve conventions. Use assets/js/components/ui and, when needed, assets/css/app.css.
4. Resolve the registry item. Read the requested manifest and its prerequisites from the registry bundled with that CLI version.
5. Build a mutation plan. Select only the detected framework's files and any direct dependencies they import.
6. Check safety. Compare every existing destination before any write.
7. Apply atomically where practical. Create missing directories, copy all planned source, add missing dependencies, and avoid partial state.
8. Report the result. Print the detected framework, resolved paths, added files, dependencies, skips, or conflicts.

Bundling versioned registry metadata with the CLI keeps one invocation deterministic: the executable and the source it installs come from the same package version.

Button, Input, and Textarea each contain one source file. Registry items can still describe prerequisite and multi-file transactions when a future compound interaction genuinely needs them. One conflicting target blocks the complete transaction before mutation.

Detection

Klean does not ask questions that the project can answer.

Evidence	Resolution
Sails package and conventional app shape	Application root
Framework dependency plus matching entry source	Vue, React, or Svelte
Boring Stack directory conventions	Component and stylesheet paths
Registry item metadata	Files and direct dependencies

When evidence conflicts or is incomplete, the command exits with the evidence it found and the relevant explicit override. It does not guess silently.

Command surface

# Add a component
npx klean-ui add button

# Inspect the full plan without writing
npx klean-ui add button --dry-run

# Use a nonstandard component destination
npx klean-ui add button --components-dir resources/js/ui

# Override a stylesheet path for an item that needs CSS
npx klean-ui add button --css resources/css/app.css

# Inspect every installed component without writing
npx klean-ui check

# Review application source against this CLI version
npx klean-ui diff button

# Safely replace one exact historical Klean revision
npx klean-ui update button

# Update every safe item and report anything skipped
npx klean-ui update --all

Exceptional paths are flags, not permanent consumer configuration.

Example output

Klean UI detected a Boring Stack application.

  Framework    React
  Components   assets/js/components/ui
  Styles       assets/css/app.css

✓ Added button/Button.jsx
✓ Added tailwind-merge

Vue installs Button.vue; React installs Button.jsx; Svelte installs Button.svelte. Only one framework implementation lands in the application.

Conflict and re-run rules

• Re-running against unchanged installed source is a no-op.
• A locally edited destination is never silently overwritten.
• Conflicts show a useful diff or require an explicit overwrite decision.
• --dry-run prints files, dependencies, and mutations without writing.
• A partial failure returns a non-zero exit code and rolls back where practical.
• Missing destination directories are created safely.

Source ownership begins at installation, so update commands inspect exact source before writing. Known earlier Klean source is safely replaceable; locally modified and untracked source is not. Read Updating for status meanings, diffs, exit codes, rollback, and recovery.

What the CLI does not create

The installer does not create:

• klean-ui.json or another project manifest;
• an init result;
• a generated cn.js or shared class helper;
• a theme provider, preset, or token file;
• a Klean component runtime;
• a framework selection prompt;
• telemetry or an account requirement.

Registry manifests are maintainer metadata inside the published package. They describe files and dependencies without becoming configuration that every consuming application must keep.