Skip to main content
No. Install globally with npm install -g @embeddables/cli. Your project only needs the files created by embeddables init (including .types/ for editor support). You do not add @embeddables/cli as a dependency in package.json for normal use.
Login is stored globally on your machine (not per project). Use embeddables logout to clear it.
You can build and save Embeddables entirely from the CLI. The Builder is still the recommended place to create new branches/experiments, upload assets, and for non-technical teammates to review and merge. Many teams use both: CLI for fast iteration and AI-assisted edits, Builder for final review and publishing.
Both must be unique in context. id is the stable internal identifier (e.g. comp_12345). key is used in React and for targeting (e.g. in conditions or user data). Keys must not start with a number; use a prefix like option_ or range_ if the label would otherwise slug to a number.
Yes. Run embeddables pull for each; they live in embeddables/<embeddable-id>/. When you run embeddables dev, embeddables save, or embeddables branch without -i, you’ll be prompted to choose which Embeddable to use. To avoid the prompt, go into that Embeddable’s folder (e.g. cd embeddables/<EMBEDDABLE_ID>) and run the command from there—the CLI will automatically use that Embeddable.
Use embeddables pull —preserve. It keeps the same order of components in the config. Most of the “changes” you see on a first pull are from React reordering components within containers—that doesn’t affect how the Embeddable renders. With —preserve, you may still see smaller changes (e.g. parent_key fixes), but it’s easier to verify what actually changed.
Use embeddables dev --local to use http://localhost:8787. Or use embeddables dev --engine https://your-engine.example.com for a custom URL.
The Workbench is a debugging panel that lets you inspect user data, computed fields, actions, and navigate pages. On localhost previews from embeddables dev, it is shown by default; add ?workbench=false to hide it. On non-localhost preview links, add ?workbench=true to show it. It is served by the dev proxy and does not require a separate deploy.
Yes. The CLI is designed for AI-assisted editing. Running embeddables init injects Cursor rules (.cursor/rules/), Claude project context (.claude/), and a Codex-compatible AGENTS.md file so the assistant understands the file layout, component types, and conventions. You can also use the built-in prompts from the CLI repo in your own rules.
Run embeddables upgrade. You can check the current version with embeddables -v.
No. You can switch to and pull existing branches with embeddables branch, and connect an Embeddable to an experiment with embeddables experiments connect, but creating new branches or experiments is done in the Builder.
Someone (in the Builder or via the CLI) saved a newer version after you last pulled. You can pull the latest with embeddables pull and then re-apply your changes, or force-save when the prompt offers it (use with care to avoid overwriting others’ work).
Global components are shared across pages (e.g. a nav bar or footer). They live in embeddables/<id>/global-components/ with one file per location, e.g. before_page.location.tsx, after_components.location.tsx. The _location value controls where they render relative to the page.
We don’t currently recommend using version control (e.g. Git) in your codebase for the Embeddable files, because it can easily get out of sync with Embeddables’ own version and branch system.Instead, use embeddables diff to compare your local files against the last saved cloud version:
embeddables diff          # latest (cloud) vs local — default
embeddables diff --depth props   # drill into individual prop changes
embeddables diff --from 46 --to 47  # compare two saved versions
For a raw JSON diff, open embeddable.json and the latest embeddable-<branch>@<version>.json (e.g. embeddable-main@47.json) inside the .generated/ folder. In VS Code or Cursor: Shift+click or Command/Ctrl+Click to select both files, then right-click → Compare Selected.
If you see a huge number of changes after pulling, try using the --preserve flag with the pull command to keep the same order of components in the config.
The Embeddables team is exploring internally various ways of integrating with version control systems like Git and GitHub.If you have any feedback or ideas on how you could envisage this working, please reach out, we’d love to bounce ideas off you!