Skip to main content

​
Core Commands

​
Setup & auth

CommandDescription
embeddables loginLog in to your Embeddables account (global).
embeddables logoutClear stored authentication.
embeddables initInitialize from inside your project folder: creates embeddables.json, .types/, embeddables/, optional Cursor/Claude/Codex prompts; creates tsconfig.json if absent, or patches it to add the required type alias paths if it already exists.
embeddables upgradeUpdate the CLI to the latest stable version.

​
Daily workflow

CommandDescription
embeddables pullFetch an Embeddable from the cloud and reverse-compile to TSX.
embeddables devStart dev server with hot reload; proxies to the Engine.
embeddables saveBuild and upload the Embeddable to the cloud.
embeddables diffCompare two versions of an Embeddable (default: latest vs local).
embeddables branchSwitch to a different branch (interactive list), then pull that branch.
embeddables builder openOpen the Embeddables Builder in your default browser for an Embeddable.
embeddables feedbackSend feedback about the CLI directly from your terminal.
You can cd embeddables/<EMBEDDABLE_ID> and run Embeddable-specific commands (dev, pull, save, branch, builder open) from there. The CLI will automatically use that Embeddable instead of prompting you to choose.

​
Assets

CommandDescription
embeddables assets uploadUpload a local asset folder to the Embeddables asset store.
embeddables assets syncSync uploaded asset metadata from the cloud into a local assets.json.

​
Build (advanced)

CommandDescription
embeddables buildCompile TSX → JSON only (no upload). Used automatically by save unless you pass --skip-build.

​
Debugging

CommandDescription
embeddables inspectFetch an Embeddable from the engine, reverse-compile to React files, rebuild to JSON, and compare the two outputs.

​
Command Options

OptionDescription
-p, —project-id <id>Set project ID (if logged in, you can pick from a list instead).
-y, —yesSkip prompts and use defaults.
OptionDescription
-i, —id <id>Embeddable ID to pull (skips interactive selection).
—version [number]Version to pull. Omit a value (—version) to open an interactive version selector. Pass a number (—version 47) to pull a specific version. Without this flag, pull defaults to the latest version.
-o, —out <path>Output path for compiled JSON (default: embeddables/<id>/.generated/embeddable.json).
-b, —branch <branch_id>Pull a specific branch.
-f, —fixRemove components with missing required props instead of erroring.
-p, —preservePreserve component order in config (see note below).
OptionDescription
-i, —id <id>Embeddable ID (prompt if not provided).
-p, —pages <glob>Custom pages glob (default: embeddables/<id>/pages/**/*.page.tsx).
-o, —out <path>Output path for compiled JSON.
-L, —localUse local engine (http://localhost:8787) instead of production.
-e, —engine <url>Engine origin (default: https://engine.embeddables.com; overridden by —local).
—port <n>Dev proxy port (default: 3000). If in use, CLI tries the next available port.
—overrideRoute <path>Route to override in proxy (default: /init).
—pageKeyFrom <mode>How to derive page keys: filename or export (default: filename).
—fixApply lint fixes (e.g. duplicate IDs, keys starting with a number).
OptionDescription
-i, —id <id>Embeddable ID (required).
-p, —pages <glob>Pages glob.
-o, —out <path>Output path for JSON.
—pageKeyFrom <mode>filename or export (default: filename).
—fixApply lint fixes.
OptionDescription
-i, —id <id>Embeddable ID (prompt if not provided).
-l, —label <label>Human-readable version label.
-b, —branch <branch_id>Branch ID to save to.
-s, —skip-buildUse existing .generated/embeddable.json (no build step).
—from-version <number>Base version (auto-detected from local config if not set).
OptionDescription
-i, —id <id>Embeddable ID (prompt from local Embeddables if not provided).
OptionDescription
-i, —id <id>Embeddable ID.
—experiment-id <id>Experiment ID (prompt to choose if not provided).
—experiment-key <key>Experiment key (required if —experiment-id is set).
OptionDescription
-i, —id <id>Embeddable ID (prompt from local Embeddables if not provided; inferred automatically if run from inside embeddables/<id>/).
OptionDescription
-i, —id <id>Embeddable ID to inspect (required).
—version <version>Version to inspect — a version number or “latest” (default: latest).
-b, —branch <branch_id>Embeddable branch ID.
-f, —fixFix by removing components missing required props (default: on).
-p, —preservePreserve component order during forward compilation (default: off). Use when you want to keep existing component order for comparison purposes.
-e, —engine <url>Engine origin (default: https://engine.embeddables.com).
OptionDescription
-i, —id <id>Embeddable ID (prompt from local Embeddables if not provided; inferred automatically if run from inside embeddables/<id>/).
—from <version>Version to compare from (default: latest). Accepts a version number, latest, staging, prod, local, or branch@version.
—to <version>Version to compare to (default: local). Same format as —from.
—depth <level>Detail level: pages, components (default), or props.
—page <keysOrIds>Filter output to specific page keys or IDs (comma-separated, no spaces).
—component <keysOrIds>Filter output to specific component keys or IDs (comma-separated, no spaces).
-b, —branch <branch_id>Branch to use when fetching cloud versions (auto-detected from config.json if not set).
-e, —engine <url>Engine origin (default: https://engine.embeddables.com).
—no-colorDisable colored output.
OptionDescription
-i, —id <id>Embeddable ID (inferred from cwd or interactive prompt if not provided).
—dir <path>Local directory to upload from (default: assets/).
—group-id <id>Target asset group ID. Resolved from project config if not provided.
—recursiveTraverse subdirectories (default: top-level only).
—include <glob>Glob pattern to include only matching files.
—exclude <glob>Glob pattern to exclude matching files.
—dry-runPreview what would be uploaded without actually uploading.
—workers <n>Number of concurrent upload workers (default: 5).
OptionDescription
-i, —id <id>Embeddable ID (inferred from cwd or interactive prompt if not provided).
—group-id <id>Asset group ID to sync. Resolved from project config if not provided.
-o, —out <path>Output path for the asset manifest (default: assets.json).
OptionDescription
[message]Optional feedback message as a positional argument. If omitted, you will be prompted interactively.
—positiveMark the feedback as positive (👍).
—negativeMark the feedback as negative (👎). Default when a message is passed non-interactively.
—category <type>Feedback area: cli, ai, compiler, or other.
pull --preserve: If you’ve held back on using the CLI because the first pull changes the JSON a lot, try embeddables pull --preserve. It keeps the same order of components in the config. The biggest cause of “changes” on pull is usually component reordering (React sorts them within containers), which doesn’t affect the rendered Embeddable. You may still see smaller changes (e.g. parent_key fixes), but it’s easier to verify what actually changed when component order stays the same.