> ## 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.

# 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/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.                              |

<Tip>
  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.
</Tip>

### 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

<AccordionGroup>
  <Accordion title="embeddables login">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>-t, --token \<token></code>
          </td>

          <td>
            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.
          </td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables init">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            `-p, --project-id <id>`
          </td>

          <td>
            Set project ID (if logged in, you can pick from a list instead).
          </td>
        </tr>

        <tr>
          <td>
            `-y, --yes`
          </td>

          <td>Skip prompts and use defaults.</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables pull">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            `-i, --id <id>`
          </td>

          <td>Embeddable ID to pull (skips interactive selection).</td>
        </tr>

        <tr>
          <td>
            `--version [number]`
          </td>

          <td>
            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.
          </td>
        </tr>

        <tr>
          <td>
            `-o, --out <path>`
          </td>

          <td>
            Output path for compiled JSON (default:{" "}
            `embeddables/<id>/.generated/embeddable.json`).
          </td>
        </tr>

        <tr>
          <td>
            `-b, --branch <branch_id>`
          </td>

          <td>Pull a specific branch.</td>
        </tr>

        <tr>
          <td>
            `-f, --fix`
          </td>

          <td>
            Remove components with missing required props instead of erroring.
          </td>
        </tr>

        <tr>
          <td>
            `-p, --preserve`
          </td>

          <td>Preserve component order in config (see note below).</td>
        </tr>

        <tr>
          <td>
            <code>--project-id \<id></code>
          </td>

          <td>Project ID for embeddable selection (skips project selection prompt).</td>
        </tr>

        <tr>
          <td>
            <code>--bypass-auth</code>
          </td>

          <td>
            Skip the login check. Intended for CI environments and automated tooling where no auth token is stored.
          </td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables dev">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            `-i, --id <id>`
          </td>

          <td>Embeddable ID (prompt if not provided).</td>
        </tr>

        <tr>
          <td>
            `-p, --pages <glob>`
          </td>

          <td>
            Custom pages glob (default:{" "}
            `embeddables/<id>/pages/**/*.page.tsx`).
          </td>
        </tr>

        <tr>
          <td>
            `-o, --out <path>`
          </td>

          <td>Output path for compiled JSON.</td>
        </tr>

        <tr>
          <td>
            `-L, --local`
          </td>

          <td>
            Use local engine (`http://localhost:8787`) instead of
            production.
          </td>
        </tr>

        <tr>
          <td>
            `-e, --engine <url>`
          </td>

          <td>
            Engine origin (default: `https://engine.embeddables.com`;
            overridden by `--local`).
          </td>
        </tr>

        <tr>
          <td>
            `--port <n>`
          </td>

          <td>
            Dev proxy port (default: `3000`). If in use, CLI tries
            the next available port.
          </td>
        </tr>

        <tr>
          <td>
            `--overrideRoute <path>`
          </td>

          <td>
            Route to override in proxy (default: `/init`).
          </td>
        </tr>

        <tr>
          <td>
            `--pageKeyFrom <mode>`
          </td>

          <td>
            How to derive page keys: `filename` or{" "}
            `export` (default: `filename`).
          </td>
        </tr>

        <tr>
          <td>
            `--fix`
          </td>

          <td>
            Apply lint fixes (e.g. duplicate IDs, keys starting with a number).
          </td>
        </tr>

        <tr>
          <td>
            <code>--bypass-auth</code>
          </td>

          <td>
            Skip the login check. Intended for CI environments and automated tooling where no auth token is stored.
          </td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables build">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            `-i, --id <id>`
          </td>

          <td>Embeddable ID (required).</td>
        </tr>

        <tr>
          <td>
            `-p, --pages <glob>`
          </td>

          <td>Pages glob.</td>
        </tr>

        <tr>
          <td>
            `-o, --out <path>`
          </td>

          <td>Output path for JSON.</td>
        </tr>

        <tr>
          <td>
            `--pageKeyFrom <mode>`
          </td>

          <td>
            `filename` or `export` (default:{" "}
            `filename`).
          </td>
        </tr>

        <tr>
          <td>
            `--fix`
          </td>

          <td>Apply lint fixes.</td>
        </tr>

        <tr>
          <td>
            <code>--bypass-auth</code>
          </td>

          <td>
            Skip the login check. Intended for CI environments and automated tooling where no auth token is stored.
          </td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables save">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            `-i, --id <id>`
          </td>

          <td>Embeddable ID (prompt if not provided).</td>
        </tr>

        <tr>
          <td>
            `-l, --label <label>`
          </td>

          <td>Human-readable version label.</td>
        </tr>

        <tr>
          <td>
            `-b, --branch <branch_id>`
          </td>

          <td>Branch ID to save to.</td>
        </tr>

        <tr>
          <td>
            `-s, --skip-build`
          </td>

          <td>
            Use existing `.generated/embeddable.json` (no build
            step).
          </td>
        </tr>

        <tr>
          <td>
            `--from-version <number>`
          </td>

          <td>Base version (auto-detected from local config if not set).</td>
        </tr>

        <tr>
          <td>
            <code>-p, --project-id \<id></code>
          </td>

          <td>Project ID (skips project selection prompt).</td>
        </tr>

        <tr>
          <td>
            <code>--force</code>
          </td>

          <td>Skip confirmation prompts (version conflicts and other users' drafts).</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables branch">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            `-i, --id <id>`
          </td>

          <td>
            Embeddable ID (prompt from local Embeddables if not provided).
          </td>
        </tr>

        <tr>
          <td>
            <code>-b, --branch \<branch\_id></code>
          </td>

          <td>Branch ID or name to switch to (skips the interactive branch selection prompt).</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables branches create">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>-i, --id \<id></code>
          </td>

          <td>
            Embeddable ID. Inferred from the current working directory or automatically when run inside <code>embeddables/\<id>/</code>; otherwise prompts to choose from local Embeddables if not provided.
          </td>
        </tr>

        <tr>
          <td>
            <code>-n, --name \<name></code>
          </td>

          <td>Branch name (required). The origin version and branch are read automatically from <code>config.json</code>. The success output includes the new branch ID returned by the server.</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables experiments create">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>-i, --id \<id></code>
          </td>

          <td>Embeddable ID (inferred from cwd or interactive prompt if not provided).</td>
        </tr>

        <tr>
          <td>
            <code>-n, --name \<name></code>
          </td>

          <td>Experiment name (required).</td>
        </tr>

        <tr>
          <td>
            <code>-k, --experiment-key \<key></code>
          </td>

          <td>Experiment key (required). Used to reference the experiment in code.</td>
        </tr>

        <tr>
          <td>
            <code>-p, --project-id \<id></code>
          </td>

          <td>Project ID (skips project selection prompt).</td>
        </tr>

        <tr>
          <td>
            <code>--variants \<list></code>
          </td>

          <td>
            Comma-separated <code>key:weight</code> pairs (e.g. <code>control:50,treatment:50</code>). Defaults to <code>control:50,treatment:50</code>. Weights must sum to 100; if they don't, the CLI will prompt to auto-adjust (or pass <code>--auto-adjust</code> to skip the prompt).
          </td>
        </tr>

        <tr>
          <td>
            <code>--status \<status></code>
          </td>

          <td>
            Initial experiment status. Valid values: <code>draft</code>, <code>active</code>, <code>paused</code>, <code>completed</code>. Defaults to <code>draft</code>.
          </td>
        </tr>

        <tr>
          <td>
            <code>--auto-adjust</code>
          </td>

          <td>Automatically scale variant weights to 100% without an interactive confirmation prompt. Useful for non-TTY/CI environments.</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables experiments connect">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            `-i, --id <id>`
          </td>

          <td>Embeddable ID.</td>
        </tr>

        <tr>
          <td>
            `--experiment-id <id>`
          </td>

          <td>Experiment ID (prompt to choose if not provided).</td>
        </tr>

        <tr>
          <td>
            `--experiment-key <key>`
          </td>

          <td>
            Experiment key (required if `--experiment-id` is set).
          </td>
        </tr>

        <tr>
          <td>
            <code>-p, --project-id \<id></code>
          </td>

          <td>Project ID (skips project selection prompt).</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables builder open">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            `-i, --id <id>`
          </td>

          <td>
            Embeddable ID (prompt from local Embeddables if not provided; inferred automatically if run from inside `embeddables/<id>/`).
          </td>
        </tr>

        <tr>
          <td>
            <code>-p, --project-id \<id></code>
          </td>

          <td>Project ID (skips project selection prompt).</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables inspect">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            `-i, --id <id>`
          </td>

          <td>Embeddable ID to inspect (required).</td>
        </tr>

        <tr>
          <td>
            `--version <version>`
          </td>

          <td>
            Version to inspect — a version number or `"latest"` (default: `latest`).
          </td>
        </tr>

        <tr>
          <td>
            `-b, --branch <branch_id>`
          </td>

          <td>Embeddable branch ID.</td>
        </tr>

        <tr>
          <td>
            `-f, --fix`
          </td>

          <td>
            Fix by removing components missing required props (default: on).
          </td>
        </tr>

        <tr>
          <td>
            `-p, --preserve`
          </td>

          <td>
            Preserve component order during forward compilation (default: off). Use when you want to keep existing component order for comparison purposes.
          </td>
        </tr>

        <tr>
          <td>
            `-e, --engine <url>`
          </td>

          <td>
            Engine origin (default: `https://engine.embeddables.com`).
          </td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables diff">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            `-i, --id <id>`
          </td>

          <td>Embeddable ID (prompt from local Embeddables if not provided; inferred automatically if run from inside `embeddables/<id>/`).</td>
        </tr>

        <tr>
          <td>
            `--from <version>`
          </td>

          <td>
            Version to compare from (default: `latest`). Accepts a version number, `latest`, `staging`, `prod`, `local`, or `branch@version`.
          </td>
        </tr>

        <tr>
          <td>
            `--to <version>`
          </td>

          <td>
            Version to compare to (default: `local`). Same format as `--from`.
          </td>
        </tr>

        <tr>
          <td>
            `--depth <level>`
          </td>

          <td>
            Detail level: `pages`, `components` (default), or `props`.
          </td>
        </tr>

        <tr>
          <td>
            `--page <keysOrIds>`
          </td>

          <td>Filter output to specific page keys or IDs (comma-separated, no spaces).</td>
        </tr>

        <tr>
          <td>
            `--component <keysOrIds>`
          </td>

          <td>Filter output to specific component keys or IDs (comma-separated, no spaces).</td>
        </tr>

        <tr>
          <td>
            `-b, --branch <branch_id>`
          </td>

          <td>Branch to use when fetching cloud versions (auto-detected from `config.json` if not set).</td>
        </tr>

        <tr>
          <td>
            `-e, --engine <url>`
          </td>

          <td>
            Engine origin (default: `https://engine.embeddables.com`).
          </td>
        </tr>

        <tr>
          <td>
            `--no-color`
          </td>

          <td>Disable colored output.</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables assets upload">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            `-i, --id <id>`
          </td>

          <td>Embeddable ID (inferred from cwd or interactive prompt if not provided).</td>
        </tr>

        <tr>
          <td>
            `--dir <path>`
          </td>

          <td>Local directory to upload from (default: `assets/`).</td>
        </tr>

        <tr>
          <td>
            `--group-id <id>`
          </td>

          <td>Target asset group ID. Resolved from project config if not provided.</td>
        </tr>

        <tr>
          <td>
            `--recursive`
          </td>

          <td>Traverse subdirectories (default: top-level only).</td>
        </tr>

        <tr>
          <td>
            `--include <glob>`
          </td>

          <td>Glob pattern to include only matching files.</td>
        </tr>

        <tr>
          <td>
            `--exclude <glob>`
          </td>

          <td>Glob pattern to exclude matching files.</td>
        </tr>

        <tr>
          <td>
            `--dry-run`
          </td>

          <td>Preview what would be uploaded without actually uploading.</td>
        </tr>

        <tr>
          <td>
            `--workers <n>`
          </td>

          <td>Number of concurrent upload workers (default: `5`).</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables assets sync">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            `-i, --id <id>`
          </td>

          <td>Embeddable ID (inferred from cwd or interactive prompt if not provided).</td>
        </tr>

        <tr>
          <td>
            `--group-id <id>`
          </td>

          <td>Asset group ID to sync. Resolved from project config if not provided.</td>
        </tr>

        <tr>
          <td>
            `-o, --out <path>`
          </td>

          <td>Output path for the asset manifest (default: `assets.json`).</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables feedback">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            `[message]`
          </td>

          <td>Optional feedback message as a positional argument. If omitted, you will be prompted interactively.</td>
        </tr>

        <tr>
          <td>
            `--positive`
          </td>

          <td>Mark the feedback as positive (👍).</td>
        </tr>

        <tr>
          <td>
            `--negative`
          </td>

          <td>Mark the feedback as negative (👎). Default when a message is passed non-interactively.</td>
        </tr>

        <tr>
          <td>
            `--category <type>`
          </td>

          <td>
            Feedback area: `cli`, `ai`, `compiler`, or `other`.
          </td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables tasks list">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>-p, --project-id \<id></code>
          </td>

          <td>
            Project ID to list tasks for. Defaults to the project configured in <code>embeddables.json</code>; prompts interactively if not set.
          </td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables tasks get">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>-i, --id \<id></code>
          </td>

          <td>Task ID (required). Displays status, priority, type, assignee, dates, body, and effort.</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables tasks update-status">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>-i, --id \<id></code>
          </td>

          <td>Task ID (required).</td>
        </tr>

        <tr>
          <td>
            <code>-s, --status \<status></code>
          </td>

          <td>
            New status (required). Valid values: <code>to\_do</code>, <code>scoping</code>, <code>in\_progress</code>, <code>feedback\_cycle</code>, <code>qa</code>, <code>blocked</code>, <code>completed</code>, <code>cancelled</code>. Hyphens are accepted in place of underscores.
          </td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables tasks assign">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>-i, --id \<id></code>
          </td>

          <td>Task ID (required).</td>
        </tr>

        <tr>
          <td>
            <code>--assignee-id \<id></code>
          </td>

          <td>User ID to assign the task to. Mutually exclusive with <code>--assign-to-owner</code>.</td>
        </tr>

        <tr>
          <td>
            <code>--assign-to-owner</code>
          </td>

          <td>Assign the task to its current owner. Mutually exclusive with <code>--assignee-id</code>.</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables tasks comment">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>-i, --id \<id></code>
          </td>

          <td>Task ID (required).</td>
        </tr>

        <tr>
          <td>
            <code>-m, --message \<content></code>
          </td>

          <td>Comment content (required).</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables tasks add-branch">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>-i, --id \<id></code>
          </td>

          <td>Task ID (required).</td>
        </tr>

        <tr>
          <td>
            <code>-b, --branch-id \<id></code>
          </td>

          <td>Branch ID to link to the task (required).</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="embeddables dangerously-publish">
    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>
            <code>-i, --id \<id></code>
          </td>

          <td>Embeddable ID (prompt if not provided).</td>
        </tr>

        <tr>
          <td>
            <code>--staging</code>
          </td>

          <td>Publish to the staging environment. Mutually exclusive with <code>--prod</code>.</td>
        </tr>

        <tr>
          <td>
            <code>--prod</code>
          </td>

          <td>Publish to production only (the version must already be on staging server-side). Mutually exclusive with <code>--staging</code>.</td>
        </tr>

        <tr>
          <td>
            <code>--via-staging</code>
          </td>

          <td>With <code>--prod</code>: push to staging first, then to production. Use when the version is not yet on staging.</td>
        </tr>

        <tr>
          <td>
            <code>--save</code>
          </td>

          <td>Build and upload a new saved version before publishing it.</td>
        </tr>

        <tr>
          <td>
            <code>--publish-version \<number></code>
          </td>

          <td>Promote this specific version number instead of reading the version from <code>config.json</code>.</td>
        </tr>

        <tr>
          <td>
            <code>-l, --label \<label></code>
          </td>

          <td>Human-readable label for the new version (only applies with <code>--save</code>).</td>
        </tr>

        <tr>
          <td>
            <code>--skip-build</code>
          </td>

          <td>Skip the build step (only applies with <code>--save</code>).</td>
        </tr>

        <tr>
          <td>
            <code>-p, --project-id \<id></code>
          </td>

          <td>Project ID (skips project selection prompt).</td>
        </tr>

        <tr>
          <td>
            <code>--force</code>
          </td>

          <td>Skip confirmation prompts (version conflicts when using <code>--save</code>, other users' drafts).</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>

<Tip>
  **`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.
</Tip>