Command Reference - Embeddables Docs

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/Gemini/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`.

Branches

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

Experiments

Command	Description
`embeddables experiments create`	Create a new experiment.
`embeddables experiments connect`	Connect an existing experiment.

Build (advanced)

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

Publishing (advanced)

Command	Description
`embeddables dangerously-publish`	Promote an existing saved version to staging or production without a full rebuild. Use with care.

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 the current working directory or automatically when run inside `embeddables/<id>/`; otherwise prompts to choose from local Embeddables if not provided.
`-n, —name <name>`	Branch name (required). The origin version and branch are read automatically from `config.json`. The success output includes the new branch ID returned by the server.

embeddables experiments create

Option	Description
`-i, —id <id>`	Embeddable ID (inferred from cwd or interactive prompt if not provided).
`-n, —name <name>`	Experiment name (required).
`-k, —experiment-key <key>`	Experiment key (required). Used to reference the experiment in code.
`-p, —project-id <id>`	Project ID (skips project selection prompt).
`—variants <list>`	Comma-separated `key:weight` pairs (e.g. `control:50,treatment:50`). Defaults to `control:50,treatment:50`. Weights must sum to 100; if they don’t, the CLI will prompt to auto-adjust (or pass `—auto-adjust` to skip the prompt).
`—status <status>`	Initial experiment status. Valid values: `draft`, `active`, `paused`, `completed`. Defaults to `draft`.
`—auto-adjust`	Automatically scale variant weights to 100% without an interactive confirmation prompt. Useful for non-TTY/CI environments.

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 dangerously-publish

Option	Description
`-i, —id <id>`	Embeddable ID (prompt if not provided).
`—staging`	Publish to the staging environment. Mutually exclusive with `—prod`.
`—prod`	Publish to production only (the version must already be on staging server-side). Mutually exclusive with `—staging`.
`—via-staging`	With `—prod`: push to staging first, then to production. Use when the version is not yet on staging.
`—save`	Build and upload a new saved version before publishing it.
`—publish-version <number>`	Promote this specific version number instead of reading the version from `config.json`.
`-l, —label <label>`	Human-readable label for the new version (only applies with `—save`).
`—skip-build`	Skip the build step (only applies with `—save`).
`-p, —project-id <id>`	Project ID (skips project selection prompt).
`—force`	Skip confirmation prompts (version conflicts when using `—save`, other users’ drafts).

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.

Documentation Index

​Core Commands

​Setup & auth

​Daily workflow

​Tasks

​Assets

​Branches

​Experiments

​Build (advanced)

​Publishing (advanced)

​Debugging

​Command Options

Core Commands

Setup & auth

Daily workflow

Tasks

Assets

Branches

Experiments

Build (advanced)

Publishing (advanced)

Debugging

Command Options