> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.embeddables.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embeddables CLI

> @embeddables/em-cli — authenticate, scaffold projects, and generate typed config for your app

## Overview

The Embeddables CLI (`em`) sets up and maintains an Embeddables project on your machine: sign in to the admin app, initialize a project, scaffold forms, connect experiments and protocols, build the generated config your app uses, and publish it to Embeddables per git branch.

Use it to manage your Embeddables project from the command line instead of hand-wiring the Core config yourself.

<Info>
  Requires Node.js 20 or newer. The npm package is `@embeddables/em-cli`; the command you run is
  `em`.
</Info>

## Install

Install globally so the `em` command used throughout these docs is on your `PATH`:

```bash theme={null}
npm install -g @embeddables/em-cli
```

<Note>
  Prefer not to install? Run it with `npx` instead — replace `em` with `npx @embeddables/em-cli` in
  every command below (for example, `npx @embeddables/em-cli init`).
</Note>

<Note>
  Add `@embeddables/em-cli` to `devDependencies` only if CI runs `em build` (or similar) and you
  want the version pinned in `package-lock.json`. For day-to-day use on your machine, global or
  `npx` is enough — the CLI is not imported by your app at runtime.
</Note>

### Update

```bash theme={null}
npm install -g @embeddables/em-cli@latest
```

`npm update -g @embeddables/em-cli` also works. Check your version with `npm list -g @embeddables/em-cli`. With `npx`, add `@latest` to always fetch the newest publish (`npx @embeddables/em-cli@latest …`).

## Quick start

<Steps>
  <Step title="Log in">
    ```bash theme={null}
    em login
    ```

    Opens the Embeddables admin app and stores a local session on your machine. Log in first — you
    need a session to select a project, connect experiments, view your data, and deploy.
  </Step>

  <Step title="Initialize the project">
    From your app root:

    ```bash theme={null}
    em init
    ```

    Sets up Embeddables in the current directory, asks which project to use, builds, and prints that
    project's sandbox and live publishable keys.
  </Step>

  <Step title="Add forms, experiments, and protocols (optional)">
    ```bash theme={null}
    em form create --name "Signup"
    em experiment connect
    em protocol connect <protocol-id>
    ```

    Optional. `form create` adds a form to your project. `experiment connect` adds an experiment from
    your project (interactive picker, or pass its id) — experiments are created in the admin first,
    so skip this if you have none yet. `protocol connect` adds a protocol from the catalog for the
    [Protocols SDK](/sdks/protocols/overview) — see [Protocols](#protocols) below.
  </Step>

  <Step title="Use it in your app">
    Import the generated config into your app — see [Core SDK](/sdks/core/overview#project-config).
    After you add or change forms or experiments, run `em build` to regenerate it.
  </Step>
</Steps>

## Commands

| Command              | Description                                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------------------- |
| `login`              | Authenticate with the Embeddables admin app and store a local session                                   |
| `logout`             | Remove the local CLI session                                                                            |
| `init`               | Set up an Embeddables project in the current directory (prompts for a project when logged in)           |
| `build`              | Build the generated config for your project                                                             |
| `deploy`             | Publish your project config to Embeddables for the current git branch (prompts unless `--skip-confirm`) |
| `form create`        | Add a form to your project and build. Use `--name` / `-n` or omit to prompt                             |
| `experiment connect` | Add an experiment from your project and build. Pass `[experimentId]` or omit to pick interactively      |
| `protocol connect`   | Download a protocol from the catalog, add it to your project, and build. Pass `<protocolId>`            |

Run `em <command> --help` for command-specific flags.

## Authentication

`login` and `logout` manage a CLI session stored locally (under your user config directory). You sign in through the Embeddables admin app at `https://admin.embeddables.com`; the CLI then talks to Embeddables production services on your behalf.

## Forms

`form create` adds a new form to your project:

```bash theme={null}
em form create --name "Checkout"
# or
em form create   # prompts: Form name:
```

It scaffolds the form and builds once your project is initialized. Display names may repeat.

## Experiments

```bash theme={null}
# Interactive picker (requires an interactive terminal)
em experiment connect

# In CI or scripts — pass the experiment id directly
em experiment connect 22222222-2222-4222-8222-222222222222
```

Adds the experiment to your project (deduped), then builds. The positional form never prompts, so it works in CI or scripts.

## Protocols

`protocol connect` adds a protocol from the Embeddables catalog to your project so the [Protocols SDK](/sdks/protocols/overview) can drive its medical intake navigation:

```bash theme={null}
em protocol connect <protocol-id>
```

Requires an active CLI session and the protocol id (there's no interactive picker). It downloads the protocol into your project, adds it to your config, and builds — so your app can import it from `embeddables/_dist`. Run it again for the same id to refresh the downloaded files.

<Note>
  Connecting a protocol adds its files to your project, but the generated React `protocols()` module
  is argument-less — your app still passes `formIds` and `protocols` explicitly. See the [Protocols
  SDK](/sdks/protocols/overview) for how to import and wire it.
</Note>

## Build

```bash theme={null}
em build
```

Validates your project and generates the config your app uses. Import it into your app — see
[Core SDK](/sdks/core/overview#project-config).

## Deploy

```bash theme={null}
em deploy
# or skip the confirmation prompt
em deploy --skip-confirm
```

Publishes your project config to Embeddables for the **current git branch**, so you must be on a checked-out branch (not a detached `HEAD`). Requires an active CLI session. It does **not** run `build` first — run `build` separately if your deployment pipeline needs fresh generated output.

## Next steps

* Wire generated config into [Core](/sdks/core/overview) and add [Analytics](/sdks/analytics/overview), [Experiments](/sdks/experiments/overview), [Forms](/sdks/forms/overview), or [Protocols](/sdks/protocols/overview) as needed.
* New to the SDKs? Start with [Quickstart](/get-started/quickstart).