@customerio/pluma-cli

Command-line tools for Pluma, Customer.io's design system. Today it ships codemods — automated migrations that move a consuming app across Pluma breaking changes — grouped by the @customerio/pluma-components version each change lands in.

Usage

No install needed — run it with pnx:

# See every codemod, grouped by the pluma-components version it targets
pnx @customerio/pluma-cli@latest upgrade --list

# Run one (always dry-run first to preview the diff)
pnx @customerio/pluma-cli@latest upgrade --codemod button-variant-rename react --dry ./src
pnx @customerio/pluma-cli@latest upgrade --codemod button-variant-rename react ./src

Or add it as a dev dependency and call the pluma-cli binary:

pnpm add -D @customerio/pluma-cli
pnpm exec pluma-cli upgrade --list

upgrade

pluma-cli upgrade --list [--json]
pluma-cli upgrade --codemod <id> <react|ember> <path...> [--dry] [--force]

After --codemod <id>, pass the framework (react or ember), then one or more paths, then any flags. Flags and paths are forwarded to the codemod, so its own options (--dry, --force, and — for React — standard jscodeshift flags) work as documented in each codemod's README.

When upgrading

1. Bump @customerio/pluma-components.
2. Run pluma-cli upgrade --list and note the codemods whose version falls in the range you're crossing.
3. Run each with --dry first, review the diff and the "needs manual review" summary, then run for real and commit.

Adding a codemod

1. Create src/codemods/<target-version>/<id>/ containing a bin.mjs dispatcher (bin.mjs <react|ember> <path…>), the react.cjs and/or ember.mjs transforms, a README.md, and a tests/ suite. Use an existing codemod as the template.
2. Register it in src/registry.ts.
3. Add a changeset so the new codemod ships in the next @customerio/pluma-cli release.

Development

pnpm --filter @customerio/pluma-cli run dev -- upgrade --list   # run from source via tsx
pnpm --filter @customerio/pluma-cli run build                   # bundle the CLI + copy transform assets to dist/
pnpm --filter @customerio/pluma-cli run test                    # vitest (CLI layer) + node --test (transforms)
pnpm --filter @customerio/pluma-cli run typecheck

The TypeScript CLI layer is bundled with pkgroll. The codemod transforms under src/codemods/ are plain JS assets copied to dist/ at build time and run in their own child processes, so they stay independently runnable and testable.