echo-ui-cli

Installs Echo UI components into your project. Its command is echo-ui.

[!IMPORTANT] Echo is not released yet. This package is a reserved name with no command behind it, so the lines below do not work today — npx echo-ui-cli resolves, installs a package with no executable, and fails with npx's own error rather than a clean "not found". They are what installing Echo will look like. This notice comes off the day it ships.

npx echo-ui-cli init          # set the project up
npx echo-ui-cli add field     # copy a component in, with what it needs
npx echo-ui-cli list          # everything in the registry
npx echo-ui-cli diff          # what has changed since you installed
npx echo-ui-cli update        # take the changes you haven't overwritten

Echo's components are copied into your source tree, not imported from a package: they are yours to read and edit. The grammar they share — the theme, sound, motion and tactile tokens — stays in the echo-ui-core package, which init installs.

What init does

• Checks the project is one Echo supports: Next.js (App Router) or Vite, React 18 or 19, TypeScript, Node 20+. Outside that it stops and says what's missing.
• Installs echo-ui-core.
• Writes echo.json (where components go, which registry), an empty echo-lock.json, and a static echo-theme.css.
• Prints the two lines you paste yourself. It never edits your files.

What add does

Resolves the items you asked for plus the Echo items they need, checks every file against the hash the registry published, and writes them under the folder in echo.json. It records what it wrote in echo-lock.json, so a later version can tell your edits from Echo's code and never silently replace yours.

A file you've edited stops the install. Pass --overwrite if you mean it.

What diff and update do

Copied files drift. diff with no arguments is a roll call — every installed item is up to date, behind, edited, or edited and behind — and diff <name> prints the actual lines that changed between your copy and the version the registry serves.

update moves the items you haven't edited and stops at the ones you have, naming them. An item moves whole or not at all, and nothing you wrote is replaced without --overwrite.

Flags

| Flag | What it does | | --- | --- | | --yes | Take the defaults, ask nothing | | --json | Machine-readable output, for agents and scripts | | --dry-run | Say what would happen; write nothing | | --overwrite | Replace files you've edited (add, update) | | --dir <path> | Where components live (init) | | --seed <hex> | The accent to build the theme from (init) | | --registry <url> | A local or staging registry | | --cwd <path> | Run against another folder | | --skip-install | Write files, don't call your package manager |

Exit codes: 0 it worked, 1 it refused and said why, 2 the command line was wrong.