Skip to main content
The Embeddables CLI is currently in Beta.Use it with caution, update the package frequently, and always check the JSON diff before saving, merging or pushing to production.
Current version: 0.11.0 — See the CLI Changelog for what’s new.
The Embeddables CLI lets you build, edit, and manage Embeddables using code instead of (or alongside) the web Builder. It turns Embeddables into TypeScript/TSX you can edit in any editor, with hot reload and strong support for AI assistants (Cursor, Claude, etc.).
Who is this for? Both technical developers (full control, scripts, CI) and non-technical builders who “vibe-code” with AI: the CLI gives you a clear file structure and prompts so AI can edit pages, styles, and logic reliably.

​
Requirements

  • Node.js >= 18.0.0

​
Installation

Install the CLI globally: 
npm install -g @embeddables/cli
Check your version: 
embeddables -v

​
Upgrading

When a new CLI version is released: 
embeddables upgrade
This installs the latest stable version from npm.

​
Quick Start

# 1. Log in (applies globally)
embeddables login

# 2. Create a project folder for your Embeddables project and go into it
mkdir my-embeddable-project
cd my-embeddable-project

# 3. Initialize from inside that folder (creates config, types, embeddables/ with subfolders per Embeddable)
embeddables init

# 4. Pull an Embeddable (interactive list if logged in)
embeddables pull

# 5. Start the dev server with hot reload
embeddables dev
After embeddables pull, you’ll have TSX pages, styles, computed fields, and actions on disk. After embeddables dev, open the Preview URL in your browser; edits to files will recompile and refresh automatically.

​
Project Structure

Run embeddables init from inside a project folder you’ve created for your Embeddables project. That folder will hold all Embeddables for that project—the CLI creates an embeddables/ directory and, as you pull, one subfolder per Embeddable (e.g. embeddables/<embeddable-id>/). embeddables init creates (or updates) project-level files. embeddables pull adds one folder per Embeddable under embeddables/: 
my-project/
├── embeddables.json          # Project ID and org (from init)
├── tsconfig.json             # TypeScript/JSX config (created by init, or patched to add type paths if it already exists)
├── default-styles.css        # Baseline styles for standard HTML tags (created by init)
├── assets.json               # Uploaded asset URLs (synced by `embeddables assets sync`)
├── .types/                   # Type stubs for editor autocomplete (no npm install needed)
├── .gitignore                # Updated to ignore .generated/ and node_modules/
├── .cursor/rules/            # Cursor AI rules (optional, from init)
├── .claude/                  # Claude project context (optional, from init)
├── AGENTS.md                 # Codex context (optional, from init)
└── embeddables/
    ├── tsconfig.json                 # TypeScript config for embeddables/ (auto-generated by pull)
    └── <embeddable-id>/
        ├── pages/                    # One .page.tsx file per page
        ├── global-components/       # Shared components (e.g. before_page.location.tsx)
        ├── styles/                  # CSS (e.g. index.css)
        ├── computed-fields/         # Custom computed field logic (.js)
        ├── actions/                 # Data output / action handlers (.js)
        ├── config.json              # Embeddable metadata, page list, version
        ├── metadata.json            # Title and basic info
        └── .generated/              # Compiled JSON (used by dev/save; avoid editing)
            ├── embeddable.json      # Current compiled output
            └── embeddable-<branch>@<version>.json   # Saved versions (for comparison)
  • Pages: pages/<pageKey>.page.tsx — React components built from Embeddable primitives.
  • Global components: One file per location (e.g. before_page.location.tsx, after_components.location.tsx).
  • config.json: Holds page keys, version, branch info; the compiler merges this with the compiled pages/styles/actions/computed fields.

​
Commands

The CLI provides commands for setup, daily workflow, building, and debugging. Here’s a quick overview:
CommandDescription
embeddables loginLog in to your Embeddables account.
embeddables initInitialize a project folder with config, types, and AI context.
embeddables pullFetch an Embeddable from the cloud and reverse-compile to TSX.
embeddables devStart the dev server with hot reload.
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, then pull that branch.
embeddables assets uploadUpload a local asset folder to the Embeddables asset store.
embeddables assets syncSync uploaded asset metadata into a local assets.json file.
embeddables buildCompile TSX to JSON without uploading.
embeddables inspectRound-trip compile and compare outputs for debugging.
embeddables feedbackSend feedback about the CLI from your terminal.

Full command reference

See all commands, flags, and options.

​
Using the CLI with AI

The CLI is built for AI-assisted editing. Running embeddables init injects context files for Cursor, Claude, and Codex so AI assistants understand Embeddable components, keys, and conventions out of the box.

AI assistant setup

Learn how to set up Cursor, Claude, and Codex for the best editing experience.

​
Next steps

Development workflow

Dev server, Workbench, TypeScript authoring, and best practices.

FAQs

Common questions about the CLI, components, and workflows.

Troubleshooting

Fix common errors and learn about current limitations.

CLI Changelog

See what’s new in each CLI release.