CLI Changelog

​

Features

• embeddables assets upload — New command that uploads a local asset folder to the Embeddables asset store. Point it at a directory (--dir <path>, default: assets/) and it validates, then uploads all supported files (images, fonts, documents, etc.) with a concurrent worker pool. Key options: --dry-run (preview what would upload without uploading), --recursive (traverse subdirectories), --include / --exclude (glob filters), --group-id (target a specific asset group), and --workers <n> (concurrency, default 5). Prints a summary of discovered/uploaded/skipped/failed files and exits non-zero on any failure.
• embeddables assets sync — New companion command that syncs project asset metadata from the cloud into a local assets.json file. assets.json becomes the source of truth for referencing uploaded asset URLs in your Embeddable (e.g. images, downloadable files). Run after uploading to keep your local manifest up to date.
• default-styles.css created by init — embeddables init now writes a default-styles.css file to the project root when it doesn’t already exist. This file provides baseline styles for standard HTML tags (buttons, inputs, links, etc.) so that Embeddables using unscoped tag selectors render consistently out of the box.

​

Bug Fixes

• experiments connect falsely marking experiments as already connected — Fixed a bug where experiments targeting the same Embeddable were incorrectly filtered out and shown as already connected, even though they hadn’t been added to the local config.json. The command now checks connected_experiments in config.json as the source of truth for local connections, rather than the server-side flow_id.
• TypeScript/React typing errors in pulled Embeddables — embeddables pull now automatically generates embeddables/tsconfig.json (with correct baseUrl and path mappings to .types/) when it doesn’t already exist. This eliminates React refers to a UMD global and Cannot find module '@embeddables/cli/components' errors that appeared in editors after pulling without first running embeddables init.

​

Improvements

• Workbench: language switcher in User Data panel — For multi-language Embeddables, the Workbench now shows a language selector dropdown next to the User Data heading. Switching languages updates all field labels and OptionSelector button texts in the Field Editor to show the localised values, and calls window.Savvy.setContentLanguage() to update the live Embeddable rendering.

​

Chores

• Workbench build script moved to src/workbench/build.ts — The internal build-workbench script is no longer in src/commands/; it has moved to src/workbench/build.ts to better reflect that it is not a public CLI command. Invoked via npm run build-workbench as before.

​

Features

• embeddables diff — New command that compares two versions of an Embeddable and reports what changed. By default it compares latest (the last saved cloud version) against local (your current working files), showing which pages and components were added, removed, or modified. Use --depth props to drill into individual prop-level changes. Filter results with --page <key> and --component <key> (comma-separated). Accepts any combination of version numbers, latest, staging, prod, or local for --from and --to.
• embeddables feedback [message] — Send feedback directly from the CLI without leaving your terminal. Run with a message (embeddables feedback "Great workflow!") or without arguments for an interactive prompt that asks for your message, sentiment (👍 positive / 👎 negative), and area (CLI, AI prompts, compiler, or other). No login required.
• branch@version version specifiers — embeddables diff --from and --to options now accept branch@version syntax (e.g. main@latest, feature-branch@47) to fetch a specific version from a specific branch, independently of the current working branch.

​

Bug Fixes

• Diff: current branch auto-detected — embeddables diff now reads the active branch from config.json automatically, so you no longer need to pass --branch explicitly when working on a non-default branch.
• Diff: key-order-independent comparison — Property insertion order in JSON objects no longer causes false positives; objects are compared semantically so only real content differences are reported.

​

Chores

• CompileErrors reported as Sentry warnings — Internal compile errors are now captured as Sentry warnings (with code frame context and file/line metadata) rather than being silently dropped or escalated as exceptions. Lint errors remain excluded from exception reporting.

​

Bug Fixes

• Custom validation functions support userData parameter — Input Box custom_validation_function now accepts an optional second parameter userData (Record<string, any>), giving your validation logic access to the full current user data. Example: function validate(value, userData) { return userData.country === 'US' ? /^\d{5}$/.test(value) : true; }.

​

Improvements

• Richer error output with code frames — Compile errors in build, dev, inspect, and save now display a highlighted code frame showing the surrounding source lines, a caret pointing to the exact column, and the file path and line number. Errors are written to stderr for consistent terminal integration.

​

Features

• embeddables inspect --preserve — The inspect command now accepts a --preserve flag to maintain component order during forward compilation. Previously inspect always preserved order; it now defaults to false (standard compilation order), and you can opt in with --preserve when you want to keep existing order for comparison purposes.

​

Improvements

• Embeddable context info box across all commands — build, dev, pull, and save now display a consistent info box showing the Embeddable title, ID, branch, and version at the start of each command, replacing the previous plain ID: … line in dev and varying formats in other commands.
• CLI help output overhauled — embeddables --help now uses Shopify CLI-style formatting with color, icons, and grouped sections for a cleaner, more readable experience.
• embeddables init output polished — The initialization header, success messages, and next-steps box have been updated: the success box now shows project title and ID; the next-steps sequence is now Pull → Run locally → Save (the Login step was removed since login is required before init); a prominent yellow beta warning box is shown at the end; and the docs link is included in the next-steps box.
• Trailing gap after all commands — All commands (login, logout, build, pull, save, inspect, builder open, experiments connect) now consistently print a trailing blank line for cleaner terminal output.
• Sentry exception enrichment — Error reports now include descriptive labels, CompileError file/line/column metadata, and additional tags (versionNumber, cliVersion, entity name tags alongside IDs) for faster debugging of production issues.

​

Bug Fixes

• Automatic Embeddable detection no longer triggers falsely in directories named embeddables/ — inferEmbeddableFromCwd() previously matched any directory whose parent was named embeddables, causing false positives when users kept projects in a folder called embeddables/ (e.g. ~/embeddables/cursor-telehealth/). The function now checks for an embeddables.json config file before treating a directory as an Embeddable project root.

​

Bug Fixes

​

Features

• Delightful CLI output overhaul — All commands now use animated spinners (via ora), compact tabular output, and concise formatting. Success moments display green boxed messages; grey info boxes show context (Embeddable ID, branch, version). Verbose file listings are consolidated into summary counts. Warnings and errors now use symbols (⚠ / ✖) instead of text badges.

​

Bug Fixes

• ESC key now consistently quits all CLI prompts — Previously, pressing ESC during interactive prompts (e.g. the email input in embeddables login, the OTP code entry, or the lint-fix confirmation in embeddables build) would silently skip the prompt and continue execution. ESC now reliably exits the process across all prompt types, including auto-complete prompts that previously resolved with the highlighted value instead of aborting.

​

Chores

• prepublishOnly build script — npm publish now automatically runs the TypeScript build step before publishing, preventing accidental releases with stale dist/ output.

​

Bug Fixes

• embeddables dev no longer loops when fixing duplicate option IDs — Fixed an infinite rebuild loop in dev mode triggered when an OptionSelector had duplicate button IDs. The fix routine now uses targeted text replacements instead of full Babel code generation, so files are only written when content actually changes. Duplicate ID detection also now covers const-referenced button arrays (e.g. buttons={someButtons}), not just inline arrays.
• TypeScript: props property now included in generated component types — The Props<T> type emitted into .types/components.d.ts by embeddables init was missing a props field, causing errors like Property 'props' does not exist on type 'Props<FileUpload>'. A props?: Record<string, any> property is now included.
• embeddables init no longer duplicates .gitignore entries — Running embeddables init more than once used to append a new # Embeddables block each time. It now replaces the existing block in-place. The generated block also adds node_modules/ and no longer unnecessarily includes **/.types/.

​

Features

• Multi-language support — The CLI now correctly handles Embeddables with multi-language content, converting between data-<language>-<property> in the JSON and the languages property in React.

​

Improvements

• embeddables pull defaults to latest version — Running embeddables pull without --version now pulls the latest version automatically, skipping the version-selection prompt. To choose a version interactively, use embeddables pull --version; to pull a specific version, pass a number: embeddables pull --version 47.

​

Bug Fixes

• Reverse compiler: global component cross-location parent_id — Fixed a round-trip bug where a global component with _location pointing to one group (e.g. before_components) but parent_id pointing to a component in a different location group (e.g. before_page) was orphaned during reverse compilation. Components are now grouped by following their parent chain rather than their own _location, keeping the component tree intact in a single TSX file.

​

Features

• embeddables builder open — Opens the Embeddables Builder in your default browser for the selected Embeddable. Resolves the project from embeddables.json (or prompts to select one if not configured), then navigates directly to the edit URL. Pass -i <id> to skip the interactive prompt, or run from inside embeddables/<id>/ to infer the Embeddable automatically.
• embeddables inspect — New debugging command that fetches an Embeddable by ID from the engine, reverse-compiles it to React/CSS/JS files, rebuilds it back to JSON, and reports which top-level keys differ between the original and rebuilt output. Designed for diagnosing round-trip compiler bugs.

​

Chores

• CI workflow improvements — Internal documentation update workflow enhanced with version input, updated permission modes, and improved branch/trigger configuration.

​

Features

• Codex (AGENTS.md) support — embeddables init now generates an AGENTS.md file at the project root, following the OpenAI Codex convention. This gives Codex the same Embeddables CLI context that Cursor and Claude already receive.

​

Bug Fixes

• Condition id now required — The id field on conditions is now required (previously optional). Use the cond_ prefix + 10 digits format (e.g. cond_1234567890), consistent with other ID conventions. Existing conditions without IDs will need one added.
• Case-insensitive sorting in CLI lists — Lists of embeddables, projects, and experiments shown in interactive prompts now sort case-insensitively using localeCompare. Previously, uppercase names (e.g. “CLI”) could sort before lowercase ones (e.g. “count”).

​

Bug Fixes

• Compiler: dataOutputs no longer dropped — Fixed a bug where dataOutputs (including webhook actions) were removed from the compiled output when the actions/ directory didn’t exist or contained no JS files. The compiler now preserves webhook actions from the config even when there are no local JS action files.
• Compiler: improved JSX string escaping — Strings containing backslashes, newlines, and double quotes are now escaped correctly when generating JSX attributes, preventing double-escaping and malformed output during round-trips.

​

Improvements

• Archived Embeddables excluded from lists — Archived Embeddables no longer appear in the interactive selection prompt when running embeddables pull or embeddables dev, keeping your lists clean and focused.

​

Features

• Local Embeddables prioritized in selection — When choosing an Embeddable to work with, locally-pulled Embeddables are now shown at the top of the list.
• embeddables init cleans up .claudefiles — If an old .claudefiles directory exists from a previous version of the CLI, init will now remove it and replace it with the correctly named .claude/ directory.

​

Features

• pull --version <number> — You can now pull a specific saved version of an Embeddable: embeddables pull --version 47. Useful for checking out an older version or recovering from a bad save.

​

Features

• Login required for all commands — The CLI now enforces authentication before running commands that require it (pull, dev, save, etc.). You’ll see a clear prompt to log in (embeddables login) rather than a cryptic API error.

​

Bug Fixes

• CMS dev mode: content_sources omitted — Fixed a proxy issue where content_sources was incorrectly included in dev mode for CMS-based Embeddables, causing unexpected behaviour. It is now correctly omitted during local development.

​

Bug Fixes

• Workbench: page selector fixed — The page selector in the Workbench panel was not working; it is now functional again.

​

Improvements

• Workbench keyboard shortcut updated — The Workbench toggle shortcut is now ⌥K (Option+K on Mac).

​

Bug Fixes

• Reverse compiler: CustomHTML uses class not className — When reverse-compiling an Embeddable to TSX, CustomHTML components now correctly generate class (HTML attribute) instead of className (React attribute) in their raw HTML content.

​

Features

• Structured error logging via Sentry — The CLI now reports errors to Sentry for improved diagnostics. Logs include context about which command was run, making it easier to debug failures.
• .claude/ directory — The Claude project context directory is now named .claude/ (previously .claudefiles/). Running embeddables init will create the correct directory. If you have an old .claudefiles/ directory, run embeddables init to migrate.

​

Bug Fixes

• Build errors handled gracefully — The CLI now exits cleanly with a helpful message on certain build errors instead of crashing with an unhandled exception.

​

Improvements

• Branch state persisted from config — embeddables pull now reads and restores the active branch from config.json, so the CLI stays on the correct branch across sessions without needing -b each time.

​

Features

• Workbench shown/hidden via query parameter — The Workbench debugging panel can now be toggled with ?workbench=true / ?workbench=false in the preview URL, without restarting the dev server.
• Custom validation functions in compiled output — Components with a custom_validation_function now compile that logic correctly into the output, based on validation_formula presence.
• Edit history tracking in save — embeddables save now includes edit history metadata when uploading, improving version tracking in the Builder.

​

Bug Fixes

• class vs className in CustomHTML — Fixed a reverse-compiler bug where class attributes inside CustomHTML were converted to className. Raw HTML attributes in custom HTML blocks are now left as-is.

​

Features

• pull --preserve — New flag to keep the existing component order in config.json when pulling. Most first-pull “changes” are React reordering components within containers—--preserve prevents that noise so you can focus on real differences. See the CLI reference for details.
• Metadata-only actions preserved — Actions that carry only metadata (no JS logic) are now correctly included in the compiled output.

​

Features

• embeddables upgrade command — New command to update the CLI to the latest stable version: embeddables upgrade. No need to remember the full npm install -g @embeddables/cli command.
• embeddables -v shows package version — The version flag now reads directly from package.json, so it always reflects the installed package version.
• Custom validation functions compiled to TypeScript — Components with custom validation logic are now reverse-compiled into typed TypeScript functions, improving editor support and type safety.

​

Bug Fixes

• Template literal escaping in button text — Strings containing ${{ ... }} (Embeddables template syntax) in button text are no longer accidentally treated as JavaScript template literal interpolations during reverse compilation.

​

Features

• --fix flag for lint auto-correction — Pass --fix to embeddables build, embeddables dev, or embeddables pull to automatically fix common issues: duplicate IDs, duplicate keys, and keys that start with a digit.

​

Bug Fixes

• Proxy error handling improved — The dev proxy server now handles connection errors more gracefully, with clearer error messages when the Engine is unreachable.

​

Features

• Branch management in pull and save — embeddables pull and embeddables save now handle branch metadata automatically, reading and writing the active branch to config.json.
• parent_key deprecation handled — The reverse compiler now detects and strips deprecated parent_key usage, replacing it with the correct parent_id-based approach.