Embeddables CLI

Build and manage Embeddables locally with code — for developers and AI-assisted builders

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

Installing Node.js and NPM on macOS

The Embeddables CLI requires Node.js (which includes NPM). If you don’t have Node.js installed:

Option 1: Using Homebrew (Recommended)

If you have Homebrew installed:

brew install node

Option 2: Download from Node.js website

1. Visit nodejs.org
2. Download the LTS (Long Term Support) version for macOS
3. Run the installer and follow the prompts

Troubleshooting on macOS:

If you see errors about missing command line tools or Xcode, you may need to install Xcode Command Line Tools first:

xcode-select --install

Click “Install” in the dialog that appears, then try installing Node.js again.

Verifying installation:

After installation, open a new terminal window and verify:

node --version
npm --version

Both commands should print version numbers.

Installing Node.js and NPM on Windows

The Embeddables CLI requires Node.js (which includes NPM). If you don’t have Node.js installed:

Option 1: Using Node.js installer (Recommended)

1. Visit nodejs.org
2. Download the LTS (Long Term Support) version for Windows
3. Run the .msi installer
4. Follow the installation wizard (keep all default options)
5. Restart your terminal or Command Prompt

Option 2: Using Chocolatey

If you have Chocolatey installed:

choco install nodejs

Verifying installation:

After installation, open a new terminal window and verify:

node --version
npm --version

Both commands should print version numbers. If you see “command not found” errors, restart your terminal or computer.

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)
├── .agent/rules/             # Antigravity IDE 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:

Command	Description
embeddables login	Log in to your Embeddables account.
embeddables init	Initialize a project folder with config, types, and AI context.
embeddables pull	Fetch an Embeddable from the cloud and reverse-compile to TSX.
embeddables dev	Start the dev server with hot reload.
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 assets upload	Upload a local asset folder to the Embeddables asset store.
embeddables assets sync	Sync uploaded asset metadata into a local assets.json file.
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.
embeddables branches create	Create a new Embeddable branch from the current local state.
embeddables build	Compile TSX to JSON without uploading.
embeddables inspect	Round-trip compile and compare outputs for debugging.
embeddables feedback	Send 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, Codex, and Antigravity 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.