Skip to content
Seamless UI

CLI

One command adds components. It always shows its plan first and never overwrites your changes.

The CLI is published as @seamlessui/cli with the binary seamless. The package is not on npm yet; see Install from a local build.

seamless add

terminal
seamless add <components...> [--dry-run] [--json] [--cwd <dir>] [--registry <url>]

| Option | What it does | | --- | --- | | --dry-run | Print the plan and exit. No files are written and no packages are installed. | | --json | Print the same plan, and the result, as JSON for scripts and coding agents. | | --cwd <dir> | Install into this app instead of the current directory. | | --registry <url> | Use another registry: a URL or a local directory. Defaults to $SEAMLESS_REGISTRY_URL, then the public registry. |

The install plan

add and --dry-run build the same plan. Registry dependencies are resolved at exact versions and installed once, so adding Tool Call Card also adds Badge. Each file gets a status:

  • add: the file does not exist yet.
  • skip: the file is identical to the registry version. Reinstalling is safe and changes nothing.
  • conflict: the file exists with different content, usually your own edits.

npm packages a component needs are listed too, and installed with the project's package manager (npm or pnpm, detected from the packageManager field and lockfiles) before any file is written. If that install fails, no component files are written.

Conflicts

If any file or package conflicts, the CLI stops before changing anything and exits with code 1:

text
Files
  conflict  src/components/seamless/ui/badge.tsx  has local changes
  add       src/components/seamless/agent/tool-call-card.tsx

Stopped: 1 conflict. No files were written and no packages were installed.

JSON output

json
{
  "ok": true,
  "plan": {
    "dryRun": true,
    "project": { "type": "next", "componentDir": "src/components/seamless" },
    "items": [{ "name": "badge", "version": "0.2.0", "requiredBy": "tool-call-card" }],
    "files": [{ "item": "badge", "path": "src/components/seamless/ui/badge.tsx", "status": "add" }],
    "dependencies": [],
    "conflicts": 0
  },
  "result": null
}

Safety

  • Destinations must stay inside the project; paths that escape through .. or a symbolic link are refused.
  • Package managers run as a fixed executable with an argument list, never through a shell.
  • Concurrent installs into one project are serialized, and files are rechecked right before writing.
  • If a write fails partway, files added by that run are removed and anything left behind is reported.