CLI

The polyhedral CLI lets you build custom sheet templates from your own editor with a live preview loop. Edit locally, save, and see changes instantly.

Installation

npm install -g @polyhedral/cli@beta

Requires Node.js 20 or later. You can also use npx @polyhedral/cli@beta without installing globally. The CLI is currently in beta — see the npm package for the latest version.

Quick Start

# 1. Log in with your API key
polyhedral login

# 2. Scaffold a new template project
polyhedral init my-sheet
cd my-sheet

# 3. Start the live preview loop
polyhedral dev

The dev command pushes your template, opens the preview page, and watches for file changes. Every time you save, the CLI validates and pushes automatically — the preview page refreshes via realtime subscriptions.

Commands

polyhedral login

Prompt for your API key, validate it, and save to ~/.polyhedral/config.json. Generate a key from Connected Apps. Requires a paid plan.

polyhedral init [dir]

Create a new directory with a starter template and polyhedral.json manifest. If no directory is given, initializes in the current directory. You'll be prompted to choose a build type: in-app (JSX, default) or external (HTML).

polyhedral list

List all your custom sheet templates in a table showing name, ID, build type, and last updated date.

polyhedral pull [id]

Download a template's code to a local file and update the manifest. If no ID is given, uses the templateId from polyhedral.json.

polyhedral push

Validate the local template file and push it to the server. Creates a new template if no templateId exists in the manifest, or updates the existing one. Prints the preview URL on success. JSX validation is skipped for external builds.

polyhedral validate [file]

Check a template file for JSX syntax errors without pushing. Reports error location (line and column) on failure. Uses the manifest file path if no file is specified. Skipped automatically for external builds.

polyhedral dev

The live development loop. Pushes the current version, opens the preview page in your browser, then watches the file for changes. On every save, the CLI validates and pushes — errors are shown in the terminal, and the preview auto-updates.

polyhedral docs

Print the full SDK reference documentation to stdout — type declarations, component library API, usage guidelines, theme variables, and example sheets. No authentication required. Use --json for machine-readable output. Useful for piping into AI assistants or other tools.

Build Types

When you run polyhedral init, you choose a build type that determines how your template is authored and processed.

In-App (default)

Write JSX using the Polyhedral component library (Sheet, Section, EditableText, etc.). The platform compiles and renders the JSX for you. Validation runs offline via Babel before each push.

# Starter file: sheet.jsx
# Manifest:     buildType: "in-app", file: "./sheet.jsx"

External

Bring your own HTML — plain HTML/JS, or the output of a bundler like Vite or webpack. You control the full document structure. The Polyhedral SDK scripts are automatically injected into <head> at render time, so you have access to Polyhedral.getField(), Polyhedral.setField(), and Polyhedral.onFieldChange() without adding any script tags yourself.

JSX validation is skipped for external builds since the file is not JSX. Use this when you want to use a framework like React, Vue, or Svelte with your own build step, write plain HTML/CSS/JS, or bundle with your own toolchain.

# Starter file: sheet.html
# Manifest:     buildType: "external", file: "./sheet.html"

Project Files

polyhedral.json

The project manifest, created by polyhedral init. Tracks the template name, server ID, file path, and metadata.

// In-app build
{
  "name": "My Sheet",
  "templateId": "uuid-here",
  "file": "./sheet.jsx",
  "buildType": "in-app",
  "description": "Optional description",
  "fieldSchema": [],
  "nameField": "name"
}

// External build
{
  "name": "My Sheet",
  "templateId": "uuid-here",
  "file": "./sheet.html",
  "buildType": "external",
  "description": "Optional description",
  "fieldSchema": [],
  "nameField": "name"
}

~/.polyhedral/config.json

Global config stored in your home directory. Contains your API key and the API URL.

{
  "apiKey": "ph_...",
  "apiUrl": "https://polyhedral.co"
}

Typical Workflow

# Log in once
polyhedral login

# Start a new sheet
polyhedral init dnd-sheet
cd dnd-sheet

# Edit sheet.jsx in your editor, then start the dev loop
polyhedral dev

# Or push manually when ready
polyhedral push

# Pull an existing template to edit locally
polyhedral pull abc123-def456

# Check what you have on the server
polyhedral list

See Also