@embeddables/em-cli

Command-line tool for Embeddables projects: authenticate, scaffold embeddables/config.yaml, connect forms, experiments, and protocols, and build the typed embeddables/_dist output your app imports.

Install

The npm package is @embeddables/em-cli; the command you run is em.

Run without installing:

npx @embeddables/em-cli login

Install globally:

npm install -g @embeddables/em-cli
em login

Or add it to a project:

npm install --save-dev @embeddables/em-cli
npx em login

Quick start

# 1. Authenticate with the Embeddables admin app
em login

# 2. Create embeddables/config.yaml (pick a project interactively)
em init

# 3. Add a form, connect an experiment, and/or install a protocol
em form create --name "Signup"
em experiment connect
em protocol install macro-dosing@example
em protocol variation install macro-dosing@example my-variation

# 4. Generate the typed embeddables/_dist output
em build

Commands

| Command | Description | | ------- | ----------- | | login | Authenticate with the Embeddables admin app and store a local session | | logout | Remove the local CLI session | | init | Create embeddables/config.yaml in the current directory (prompts for a project) | | build | Validate embeddables/config.yaml and write embeddables/_dist (config.ts, index.ts, forms/*/schema.ts, and a single generated protocols/<id>/<version>/schema.ts inlining the vendored base and any configured variations) | | deploy | Publish embeddables/config.yaml to Embeddables for the current git branch (prompts unless --skip-confirm) | | form create | Add a form to embeddables/config.yaml, scaffold forms/<id>/schema.yaml, and build. Omit --name to be prompted | | experiment connect | Add an experiment id to embeddables/config.yaml and build. Omit the id to pick one interactively | | protocol install <protocol-id> [version-id] | Fetch schema/README from the catalog, vendor under embeddables/_protocols/, update config (replace version on upgrade), and build. Upgrading to a different version clears configured variations; the next build includes only the base protocol until variations are reinstalled, and the CLI warns with the full protocol variation install command for each removed variation. On upgrade, keeps old vendored files by default; use --no-keep-old-version to delete them | | protocol variation install <protocol-id> [version-id] <variation-id> | Fetch a variation schema/README from the catalog, vendor under embeddables/_protocols/<id>/<version>/variations/<variation-id>/, append the variation id to config, and build. Base protocol must already be installed | | protocol uninstall <protocol-id> <version-id> | Remove a protocol version from embeddables/config.yaml, delete its vendored files under embeddables/_protocols/<id>/<version>/, and build |

Run em <command> --help for command-specific usage.

Notes

• init and build require an authenticated session when the config references a project UUID or lists experiments; run em login first.
• protocol install and protocol variation install require an active session, a UUID projectId in embeddables/config.yaml, project membership, and the relevant project allowlist to fetch from the catalog.
• build fetches experiments when experiments: lists ids, reads vendored protocol sources from embeddables/_protocols/ and generates inlined, import-free embeddables/_dist/protocols/<id>/<version>/schema.ts bundles, and runs offline otherwise.
• Requires Node.js 20+.
• Global install (npm i -g @embeddables/em-cli) registers the em command. An unrelated unscoped npm package em-cli also ships a bin named em; if both are installed globally, only one em command will win on your PATH. Prefer npx @embeddables/em-cli when in doubt.