Embeddables CLI (development)

This repo is the source for @embeddables/cli — the CLI for authoring and managing Embeddables locally with TypeScript/TSX. If you only want to use the CLI, see the package on npm or the user-facing README (same content as the npm package page).

Prerequisites

• Node.js >= 18.0.0

Setup

git clone <this-repo>
cd embeddables-cli
npm install

Scripts

| Script | Description | | ----------------------- | ----------------------------- | | npm run build | Compile TypeScript to dist/ | | npm run build:watch | Watch and recompile on change | | npm test | Run tests (Vitest) | | npm run test:watch | Run tests in watch mode | | npm run test:coverage | Coverage report | | npm run lint | ESLint | | npm run format | Prettier (write) | | npm run format:check | Prettier (check only) | | npm run build-workbench | Build Workbench bundle for CDN (e.g. -- --out workbench-worker) |

Local testing

After building, link the CLI so you can run embeddables from another project:

npm run build
npm link

Then in a project that uses the CLI (e.g. an embeddables app), run embeddables <command> — it will use your linked build. Unlink with npm unlink -g @embeddables/cli when done.

You can also run the CLI without installing, from this repo:

npx tsx src/cli.ts dev
# or
npx tsx src/cli.ts build -i <embeddable-id>

Project structure

• src/cli.ts — Commander setup and command registration
• src/commands/ — Implementations for init, login, logout, pull, branch, build, save, dev
• src/compiler/ — TSX → JSON compile and JSON → TSX reverse-compile
• src/config/ — embeddables.json and project config
• src/auth/ — Login/logout and token storage
• src/prompts/ — Interactive prompts (projects, embeddables, branches)
• src/proxy/ — Dev server and engine proxy
• src/workbench/ — Visual debugging UI and CDN build script (build.ts)
• src/components/ — React primitives exported as @embeddables/cli/components
• bin/embeddables.mjs — Entry script that runs dist/cli.js
• scripts/run-build-workbench.ts — Entry for npm run build-workbench (invokes src/workbench/build.ts for CDN deploy)
• tests/ — Unit and integration tests (Vitest)

Publishing

The user-facing README is in package-readme.md. It is swapped in as README.md during npm pack / npm publish via prepack/postpack scripts so the npm package shows the right docs. Do not remove those scripts.

User documentation

Full command reference, installation, and usage for people who install the package: package-readme.md.