> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embeddables.com/llms.txt
> Use this file to discover all available pages before exploring further.
# CLI Changelog
> Version history for the Embeddables CLI (@embeddables/cli)
Install or upgrade: `npm install -g @embeddables/cli`
Check your version: `embeddables -v`
***
### Features
* **Workbench: page thumbnail strip** — A new toggleable thumbnail row below the Workbench shows a preview of every page in the Embeddable, with the current page highlighted and auto-centered. Click a thumbnail to jump via `Savvy.goToPage`; drag the divider to resize the strip. Thumbnails use the Engine's static HTML when available and derive their viewport from the Flow's breakpoints, and pages hidden or gated by unmet conditions or experiments are dimmed in both the page navigator dropdown and the thumbnail row. Strip visibility and height persist in `WorkbenchPrefs` (localStorage), the list is virtualized with `@tanstack/react-virtual`, and the strip is hidden by default.
* **Workbench: action-debug toast toggle** — A new bolt button in the Workbench toggles action-debug toasts on/off and syncs the `savvy_debug` URL param (preserving `history.state` and removing the param on toggle-off so a reload reflects the new state). Includes `aria-label`/`aria-pressed` for accessibility.
### Chores
* **AI prompt rules: Actions and multilingual guidance** — Consumer AI context now documents the full `output()` second-arg helper API (`setUserData`, `goToPage`, `goToNextPage`, `trackCustomEvent`) with destructuring examples, clarifies that computed fields typically only use `trackCustomEvent`, and adds Flow-level `languages` config plus end-user runtime language behavior (browser-locale scope in published runtime, exact vs regional key matching, opt-in `outputs_onloadflow` defaults). The global language picker is reframed as a stakeholder-driven, design-agnostic pattern (any UI that sets `embeddable_language`; `OptionSelector` shown as one common example).
* **doc-templates AI README: Markdown and JSX typography** — Internal doc-templates AI context clarifies Markdown vs JSX usage in typography: documents automatic class application for standard HTML headings/paragraphs and the explicit JSX requirements for custom styling, with an improved table layout.
### Bug Fixes
* **Global component insert positions in JSON diff → edit history** — Fixed `src/helpers/json.ts` so that insert anchors for components added in a diff are scoped by their `_location` (global slot vs. page-level bucket). Sibling ordering now uses only true ordering peers (same parent or same `_location`), the `isGlobalComponents` flag is passed for root globals, and `insertedComponentId` is excluded from anchor resolution so a component can never anchor against itself. Move-command logic was also tightened to preserve component hierarchy across global slots.
### Chores
* **PR template: Decisions section** — The repo's pull request template now leads with a `Decisions` section capturing approach, tradeoffs, and alternatives so reviewers see key decisions at the top of the PR. Contributor-facing only.
### Improvements
* **Per-operation edit history on save and publish** — `embeddables save` and `embeddables dangerously-publish` now emit per-change `editHistoryDescriptions` matching the Builder's format (e.g. `Set component login_btn [id: comp_123] property text to "Continue"`, `Add component cta_button in page welcome`, `Move page checkout`, `Remove tag draft from Page welcome`). Previously each save/publish recorded a single generic `Saved version from CLI` entry. Descriptions are capped at 100 entries with an overflow marker, mirroring the Builder. The `trigger.editor` field on save/publish now records the actual user ID instead of the literal string `"CLI"`.
### Chores
* **AI-README: PR title workflow for Linear issues** — Internal contributor guide updated with the PR title format used for Linear-tracked work.
### Features
* **`disable_button_until_page_valid` for `StripeCheckout2`** — `StripeCheckout2` now accepts a `disable_button_until_page_valid` boolean prop. When set to `true`, the payment button stays disabled until all page-level validation passes, preventing premature payment attempts before required fields are complete.
### Bug Fixes
* **Workbench: removed nonexistent `setContentLanguage` call** — The Workbench language switcher was calling `window.Savvy.setContentLanguage()`, which does not exist in the engine. The no-op call has been removed; language switching continues to work correctly via `setUserData` with the language key.
### Chores
* **AI prompt rules: `window.Embeddables.trackCustomEvent`** — Consumer AI context updated to reference `window.Embeddables.trackCustomEvent()` for host-page custom event tracking, replacing the legacy `window.Savvy.trackCustomEvent()` reference.
* **AI prompt rules: legacy `experiments` array prohibited** — Consumer AI context now explicitly prohibits writing the top-level `experiments` array on a Flow. `connected_experiments` is the only field AI agents may write for experiment connections, preventing experiments from disappearing from the Experiments UI.
### Features
* **`embeddables experiments create`** — New command that creates an experiment for one or more Embeddables. Accepts `-i, --id ` (Embeddable ID), `-n, --name ` (experiment name), `-k, --experiment-key `, `-p, --project-id `, `--variants ` (comma-separated `key:weight` pairs; defaults to `control:50,treatment:50`), `--status ` (defaults to `draft`), and `--auto-adjust` (automatically scale variant weights to 100% without an interactive prompt when weights don't sum to 100).
* **`GEMINI.md` emitted on `init` / `upgrade`** — `embeddables init` and `embeddables upgrade` now also write a `GEMINI.md` file at the project root, following the same short-pointer convention as `AGENTS.md`. Gemini CLI will automatically load the shared `AI-README.md` development guide.
* **`languages` property support** — The top-level `languages` array is now recognised in Flow types. A new `EmbeddableLanguage` type (`{ key: string; name: string }`) is exported from `.types/`, and `infobox_use_dialog_element` is also added to the Flow type to align with the Builder.
### Bug Fixes
* **Stripe/PayPal payment trigger output props** — `on_payment_complete_outputs`, `on_payment_failed_outputs`, and `on_payment_attempted_outputs` on `StripeCheckout`, `StripeCheckout2`, and `PaypalCheckout` components now render as first-class named JSX props in the reverse compiler instead of falling into the `props={}` catch-all.
* **`InputBox.max_length` type** — The `max_length` prop on `InputBox` is now typed as `number` (matching the Builder), not `string`.
* **`embeddables init` spinner** — The "Fetching projects…" spinner is now cleared before the interactive project selection prompt is shown, preventing the spinner text from persisting below the list during the entire selection interaction.
* **`embeddables pull` fails on missing Embeddable** — `pull` now exits with a clear error when the remote Embeddable is missing (empty-flow fallback response or 404), rather than silently writing a broken local repo.
### Improvements
* **`embeddables diff` shows item names** — Changes to `computedFields` and `actions` (dataOutputs) in diff output now list each affected item by name/key/id (`- removed`, `+ added`, `~ modified`) instead of a generic `[N items] → [M items]` summary.
### Chores
* **AI prompt rules updated** — Internal `.prompts` context updated: `track_clicks` added to `CustomButton` guidance; `languages` property clarification added; payment component trigger-type table now correctly includes legacy `StripeCheckout` alongside `StripeCheckout2` and `PaypalCheckout`.
### Features
* **Workbench: Feedback Panel** — A new Feedback panel in the Workbench lets you submit annotated feedback on an Embeddable directly from the preview. Supports image paste (including on Windows), session upload management, tagging, and a shared session welcome modal. Feedback is stored with the project ID from `embeddables.json`, injected automatically in dev mode.
* **`embeddables dangerously-publish`** — New command that promotes an existing saved version to staging or production without a full rebuild. Requires exactly one of `--staging` or `--prod`. Use `--via-staging` with `--prod` if the version is not yet on staging. Pass `--save` to upload a new saved version first, or `--publish-version ` to target a specific version instead of reading from `config.json`.
* **`embeddables inspect`: fixable failures shown as warnings with fix-and-retry prompt** — When `inspect` encounters component-level issues that can be auto-fixed (e.g. missing required props), it now displays a warning and prompts you to retry with `--fix` rather than exiting immediately. The prompt defaults to yes, preserving the previous auto-fix feel. Matches the existing behaviour in `embeddables pull`.
* **`OptionSelector` placeholder prop** — `OptionSelector` now accepts a first-class `placeholder` prop with full multi-language translation support.
* **Workbench: Reset User Data toast** — The Workbench now shows a toast confirmation when user data is reset.
### Bug Fixes
* **Workbench: image paste on Windows** — Pasted images are now accepted when the clipboard item's MIME type is empty, which occurs in some Windows browsers and clipboard sources.
* **`embeddables save`: 500 error response body surfaced** — When the server returns a 500 during `save`, the response body is now parsed and included in the displayed error message.
* **`embeddables init` / `upgrade`: single Claude rule file** — `embeddables init` and `upgrade` now write `.claude/CLAUDE.md` only; the legacy `.claude/embeddables-cli.md` file is removed on upgrade. Aligns with Claude Code conventions and avoids duplicate context.
* **Workbench: toast notification fixes** — Toast is now positioned above the Workbench bar (outside the panel), aligned to the right, with improved contrast (solid success/error colors), correct state reset when the Embeddable ID changes, and proper timer cleanup on unmount.
### Features
* **Shared `AI-README.md` + short pointer rule files** — `embeddables init` now creates a shared `AI-README.md` at the project root containing the full Embeddables CLI development guide. The AI editor rule files for Cursor (`.cursor/rules/embeddables-cli.md`), Claude (`.claude/embeddables-cli.md`), Codex (`AGENTS.md`), and Antigravity (`.agent/rules/embeddables-cli.md`) are now concise pointer files that reference `AI-README.md`, rather than each duplicating the full content. This keeps rule files small and ensures they stay in sync.
* **`embeddables upgrade` refreshes AI context files and type stubs** — Running `embeddables upgrade` now also regenerates AI rule files and `.types/` type stubs in the project to match the newly installed CLI version, so they stay up to date automatically without needing to re-run `embeddables init`.
* **`preserve_json_in_cli` for `CustomHTML`** — `CustomHTML` components now accept a `preserve_json_in_cli` boolean prop. When set, the HTML content is preserved as-is during CLI round-trips, bypassing HTML reformatting. Useful for raw embeds that should not be touched by the compiler.
### Bug Fixes
* **Workbench: `OptionSelector` dropdown autofill** — Dropdowns in the Workbench field editor now autofill correctly. Fixed by removing an empty-buttons guard and switching to `setUserData` for consistent state propagation.
* **`embeddables branch`: soft-deleted branches hidden** — Soft-deleted branches are now filtered out of the interactive branch selection prompt, keeping the list clean.
* **`CustomHTML`: whitespace trimming and hyphenated SVG attributes** — Whitespace in `CustomHTML` text content is now trimmed correctly; hyphenated SVG attributes (e.g. `stroke-width`, `fill-rule`, `stroke-linecap`) are preserved through round-trips.
* **`embeddables pull`: reduced style-only diffs** — Fixed an issue where pulling could introduce unwanted whitespace changes in `CustomHTML` serialization, causing spurious diffs.
* **Edit history: array value diffs** — Array-type values in edit history now diff correctly when saving, preventing spurious change records.
* **Page-level trigger output types** — Page-level outputs now correctly identify trigger output types, improving type safety.
### Improvements
* **Computed field and action function signatures** — `result()` and `output()` now accept the full three-argument form (`userData`, `helperFunctions`, `triggerContext`). Trailing unused parameters can be omitted, keeping simple computed fields concise.
### Chores
* **AI prompt guidance for disabled CTAs** — Internal AI context updated with the `needs_validation_passed` + `validation_show_state` pattern for implementing disabled CTA button states.
### Improvements
* **`addTaskBranch` now stores `project_id`** — When a branch is associated with a task, the CLI now correctly includes `project_id` in the `task_branches` database record alongside `task_id` and `branch_id`. A debug log line is also emitted during the insertion, improving visibility for branch operations in development.
### Improvements
* **`branches create` success message shows branch ID** — After successfully creating a branch, the CLI now displays both the branch name and the branch ID (as returned by the server) in the success box, making it easier to reference the new branch in subsequent commands such as `embeddables pull -b ` or `embeddables save -b `.
### Chores
* **CLI option formatting** — Internal option definitions in the CLI entry point have been reformatted for consistency and readability; no user-facing changes.
### Features
* **`embeddables branches create`** — New command that creates a new branch from the current Embeddable state. Resolves the Embeddable from `--id`, the current working directory, or an interactive prompt; reads the origin version and branch from `config.json`. Use `-n, --name ` to set the branch name (required). Requires login.
* **`embeddables branch --branch` option** — `embeddables branch` now accepts `-b, --branch ` to switch directly to a known branch ID or name without going through the interactive selection list.
### Chores
* **`branches` recognised as a utility command** — The `branches` subcommand group is now listed in the utility commands set, so branch management commands are correctly grouped in `embeddables --help` output.
### Features
* **`embeddables tasks`** — New command group for managing project tasks directly from the terminal. All subcommands require login and resolve the project from `embeddables.json` or an interactive prompt:
* **`tasks list`** — Print a compact table of all tasks for the current project (`-p, --project-id ` to skip the prompt).
* **`tasks get -i `** — Show full details of a single task by ID.
* **`tasks update-status -i -s `** — Change a task's status. Valid values: `to_do`, `scoping`, `in_progress`, `feedback_cycle`, `qa`, `blocked`, `completed`, `cancelled`.
* **`tasks assign -i `** — Reassign a task. Pass `--assignee-id ` to assign to a specific user or `--assign-to-owner` to assign back to the task owner.
* **`tasks comment -i -m `** — Add a comment to a task.
* **`tasks add-branch -i -b `** — Link an Embeddable branch to a task.
* **`embeddables branches create`** — New subcommand that creates a new Embeddable branch from the current local state. Pass `-n, --name ` for the branch name; the origin version and branch are read automatically from `config.json`. Requires login.
### Chores
* **Expanded CLI help and README** — `embeddables --help` output and the package README now include full option documentation for `inspect`, `diff`, `feedback`, `builder open`, `experiments connect`, `assets upload`, `assets sync`, and all task management commands.
### Features
* **Non-interactive flags for all commands** — Every interactive prompt in the CLI (excluding `login`) now has a corresponding flag, making all commands fully scriptable for use in CI pipelines, AI-driven workflows, and automation:
* **`embeddables branch`**: `--branch ` skips the branch selection prompt.
* **`embeddables save`**: `--project-id ` skips the project selection prompt; `--force` skips all confirmation prompts (version conflicts and other users' drafts).
* **`embeddables pull`**: `--project-id ` skips the project selection prompt.
* **`embeddables builder open`**: `--project-id ` skips the project selection prompt.
* **`embeddables experiments connect`**: `--project-id ` skips the project selection prompt.
### Features
* **`embeddables tasks` command group** — New commands for managing project tasks directly from the CLI. All subcommands require login and resolve the project from `embeddables.json` or prompt interactively.
* **`tasks list`** — Display a table of all tasks for the current project (`-p, --project-id ` to target a specific project).
* **`tasks get`** — Fetch and display full details for a single task (`-i, --id `): status, priority, type, assignee, dates, body, and effort.
* **`tasks update-status`** — Change a task's status (`-i, --id `, `-s, --status `). Valid values: `to_do`, `scoping`, `in_progress`, `feedback_cycle`, `qa`, `blocked`, `completed`, `cancelled`.
* **`tasks assign`** — Change a task's assignee (`-i, --id `, then either `--assignee-id ` or `--assign-to-owner` to assign to the task's owner).
* **`tasks comment`** — Add a comment to a task (`-i, --id `, `-m, --message `).
* **`tasks add-branch`** — Link an Embeddables branch to a task (`-i, --id `, `-b, --branch-id `).
* **`embeddables login --token `** — New `-t, --token` option for non-interactive, token-based login. Pass a JWT directly instead of going through the OTP email flow — ideal for CI pipelines and cloud containers where interactive prompts are unavailable.
* **`--bypass-auth` flag for `pull`, `dev`, and `build`** — Hidden flag that skips the login check, allowing these commands to run without a stored auth token. Intended for CI environments and automated tooling. (`save` continues to require login.)
### Improvements
* **Workbench: in-app modal dialogs in User Data panel** — The User Data panel in the Workbench now uses proper in-app modal dialogs instead of native browser `window.prompt()` calls. Both the "Save Persona" and "Go To Page" actions open a focused modal with a text input, inline error display, and keyboard shortcuts (Enter to confirm, Escape to dismiss). This also fixes the Workbench on Cursor Cloud, where native browser dialogs are not supported.
### Chores
* **AI development guidelines added to internal dev context** — `AI-README.md` now includes an "AI Development Guidelines" section covering code comment conventions, testing requirements, and an end-of-workflow inconsistency check. `CLAUDE.md` and `AGENTS.md` tables-of-contents were updated to reference the new section.
* **Cursor Cloud instructions in developer docs** — `AI-README.md` and `AGENTS.md` now include specific setup and usage instructions for working within Cursor Cloud, including notes on CLI-only commands and test video recording guidelines.
* **Developer guide centralized in `AI-README.md`** — `AGENTS.md`, `CLAUDE.md`, and `.cursor/rules/embeddables-dev.md` now point to `AI-README.md` as the single source of truth for the internal development guide.
### Features
* **Antigravity IDE support in `embeddables init`** — `embeddables init` now creates `.agent/rules/embeddables-cli.md` for [Antigravity](https://antigravity.dev), joining Cursor (`.cursor/rules/`), Claude (`.claude/`), and Codex (`AGENTS.md`) as a supported AI editor. The file is generated with the correct Antigravity frontmatter (`globs`, `alwaysOn`) and the same full Embeddables CLI context injected into other editors.
* **`_docs` property** — Embeddables now support a `_docs` property for documenting non-obvious aspects of your configuration. It can be set at the top level, on individual pages, computed fields, and data outputs. The value is preserved through pull and save round-trips unchanged, making it safe to add inline documentation to your `config.json` without it being stripped.
### Bug Fixes
* **Video mute/play state lost on `pull`** — Fixed two root causes that caused `
### Features
* **`embeddables assets upload`** — New command that uploads a local asset folder to the Embeddables asset store. Point it at a directory (`--dir `, 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 ` (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 ` and `--component ` (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`), 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
— Fixed an infinite loop in the HTML→JSX conversion function triggered when component HTML content begins with a declaration tag such as `` or a processing instruction like ``. These non-element tags are now skipped cleanly. A secondary guard was also added so the parser always advances past any `<` character it cannot match, preventing the loop from stalling regardless of the malformed input.
### Features
* **Delightful CLI output overhaul** — All commands now use animated spinners (via [ora](https://github.com/sindresorhus/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` 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'`. A `props?: Record` 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--` 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 ` to skip the interactive prompt, or run from inside `embeddables//` 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 `** — 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](/cli#pull-preserve) 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.