Command Reference

Complete reference for all Embeddables CLI commands and their options

Core Commands

Setup & auth

Command	Description
embeddables login	Log in to your Embeddables account (global).
embeddables logout	Clear stored authentication.
embeddables init	Initialize from inside your project folder: creates embeddables.json, .types/, embeddables/, optional Cursor/Claude/Codex/Antigravity prompts; creates tsconfig.json if absent, or patches it to add the required type alias paths if it already exists.
embeddables upgrade	Update the CLI to the latest stable version.

Daily workflow

Command	Description
embeddables pull	Fetch an Embeddable from the cloud and reverse-compile to TSX.
embeddables dev	Start dev server with hot reload; proxies to the Engine.
embeddables save	Build and upload the Embeddable to the cloud.
embeddables diff	Compare two versions of an Embeddable (default: latest vs local).
embeddables branch	Switch to a different branch (interactive list or --branch), then pull that branch.
embeddables branches create	Create a new branch from the current Embeddable state.
embeddables builder open	Open the Embeddables Builder in your default browser for an Embeddable.
embeddables feedback	Send 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.

Tasks

Command	Description
embeddables tasks list	List all tasks for the current project.
embeddables tasks get	Fetch full details for a task by ID.
embeddables tasks update-status	Change a task’s status.
embeddables tasks assign	Change a task’s assignee.
embeddables tasks comment	Add a comment to a task.
embeddables tasks add-branch	Link an Embeddables branch to a task.

Assets

Command	Description
embeddables assets upload	Upload a local asset folder to the Embeddables asset store.
embeddables assets sync	Sync uploaded asset metadata from the cloud into a local assets.json.

Tasks

Command	Description
embeddables tasks list	List all tasks for the current project.
embeddables tasks get	Get details of a specific task by ID.
embeddables tasks update-status	Update a task’s status.
embeddables tasks assign	Change the assignee of a task.
embeddables tasks comment	Add a comment to a task.
embeddables tasks add-branch	Link an Embeddable branch to a task.

Branches

Command	Description
embeddables branches create	Create a new Embeddable branch from the current local state.

Build (advanced)

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

Debugging

Command	Description
embeddables inspect	Fetch an Embeddable from the engine, reverse-compile to React files, rebuild to JSON, and compare the two outputs.

---

Command Options

embeddables login

Option	Description
-t, —token <token>	Use a token for non-interactive login. Pass a JWT directly instead of going through the OTP email flow — ideal for CI pipelines and cloud containers. The token’s expiry is parsed from the JWT payload and stored alongside the session.

embeddables init

Option	Description
-p, --project-id <id>	Set project ID (if logged in, you can pick from a list instead).
-y, --yes	Skip prompts and use defaults.

embeddables pull

Option	Description
-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, --fix	Remove components with missing required props instead of erroring.
-p, --preserve	Preserve component order in config (see note below).
—project-id <id>	Project ID for embeddable selection (skips project selection prompt).
—bypass-auth	Skip the login check. Intended for CI environments and automated tooling where no auth token is stored.

embeddables dev

Option	Description
-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, --local	Use 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).
--fix	Apply lint fixes (e.g. duplicate IDs, keys starting with a number).
—bypass-auth	Skip the login check. Intended for CI environments and automated tooling where no auth token is stored.

embeddables build

Option	Description
-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).
--fix	Apply lint fixes.
—bypass-auth	Skip the login check. Intended for CI environments and automated tooling where no auth token is stored.

embeddables save

Option	Description
-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-build	Use existing .generated/embeddable.json (no build step).
--from-version <number>	Base version (auto-detected from local config if not set).
-p, —project-id <id>	Project ID (skips project selection prompt).
—force	Skip confirmation prompts (version conflicts and other users’ drafts).

embeddables branch

Option	Description
-i, --id <id>	Embeddable ID (prompt from local Embeddables if not provided).
-b, —branch <branch_id>	Branch ID or name to switch to (skips the interactive branch selection prompt).

embeddables branches create

Option	Description
-i, —id <id>	Embeddable ID (inferred from cwd or interactive prompt if not provided).
-n, —name <name>	Branch name (required). The success output will include the new branch ID returned by the server.

embeddables experiments connect

Option	Description
-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).
-p, —project-id <id>	Project ID (skips project selection prompt).

embeddables builder open

Option	Description
-i, --id <id>	Embeddable ID (prompt from local Embeddables if not provided; inferred automatically if run from inside embeddables/<id>/).
-p, —project-id <id>	Project ID (skips project selection prompt).

embeddables inspect

Option	Description
-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, --fix	Fix by removing components missing required props (default: on).
-p, --preserve	Preserve 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).

embeddables diff

Option	Description
-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-color	Disable colored output.

embeddables assets upload

Option	Description
-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.
--recursive	Traverse subdirectories (default: top-level only).
--include <glob>	Glob pattern to include only matching files.
--exclude <glob>	Glob pattern to exclude matching files.
--dry-run	Preview what would be uploaded without actually uploading.
--workers <n>	Number of concurrent upload workers (default: 5).

embeddables assets sync

Option	Description
-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).

embeddables feedback

Option	Description
[message]	Optional feedback message as a positional argument. If omitted, you will be prompted interactively.
--positive	Mark the feedback as positive (👍).
--negative	Mark the feedback as negative (👎). Default when a message is passed non-interactively.
--category <type>	Feedback area: cli, ai, compiler, or other.

embeddables tasks list

Option	Description
-p, —project-id <id>	Project ID to list tasks for. Defaults to the project configured in embeddables.json; prompts interactively if not set.

embeddables tasks get

Option	Description
-i, —id <id>	Task ID (required). Displays status, priority, type, assignee, dates, body, and effort.

embeddables tasks update-status

Option	Description
-i, —id <id>	Task ID (required).
-s, —status <status>	New status (required). Valid values: to_do, scoping, in_progress, feedback_cycle, qa, blocked, completed, cancelled. Hyphens are accepted in place of underscores.

embeddables tasks assign

Option	Description
-i, —id <id>	Task ID (required).
—assignee-id <id>	User ID to assign the task to. Mutually exclusive with —assign-to-owner.
—assign-to-owner	Assign the task to its current owner. Mutually exclusive with —assignee-id.

embeddables tasks comment

Option	Description
-i, —id <id>	Task ID (required).
-m, —message <content>	Comment content (required).

embeddables tasks add-branch

Option	Description
-i, —id <id>	Task ID (required).
-b, —branch-id <id>	Branch ID to link to the task (required).

embeddables branches create

Option	Description
-i, —id <id>	Embeddable ID (prompt from local Embeddables if not provided; inferred automatically if run from inside embeddables/<id>/).
-n, —name <name>	Branch name (required). The origin version and branch are read automatically from config.json.

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.