@polyhedral/cli

CLI for building custom character sheet templates on Polyhedral. Edit locally in your own editor, push to the server, and preview changes live.

Install

npm install -g @polyhedral/cli

Requires Node.js 20+. Or use npx @polyhedral/cli without installing.

Updates

The CLI keeps itself up to date. Once a day it checks npm for a newer build on its channel (a beta build follows beta). When it finds one, it installs it in the background after your command finishes, and the next run tells you it updated. This works for global installs through npm, pnpm, yarn, or bun.

If it can't update itself, it tells you the command to run instead. That happens when the global folder needs sudo, in CI, and in non-interactive runs. Set POLYHEDRAL_NO_AUTO_UPDATE=1 to turn self-updating off, or NO_UPDATE_NOTIFIER=1 to turn off the check entirely.

Quick Start

# Log in with your API key (get one from Developer Tools in your avatar menu)
polyhedral login

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

# Start the live preview loop — edit, save, see it update
polyhedral dev

Commands

| Command | Description | | --------------------- | ------------------------------------------------- | | polyhedral login | Authenticate with your API key | | polyhedral logout | Remove stored credentials | | polyhedral whoami | Show current login status | | polyhedral init | Scaffold a new template project | | polyhedral dev | Watch file, auto-push on save, open live preview | | polyhedral push | Validate, upload, and publish a new version | | polyhedral pull | Download a template to a local file | | polyhedral delete | Delete a template | | polyhedral list | List all your custom sheet templates | | polyhedral versions | List version history for a template | | polyhedral validate | Check a template file for syntax errors (offline) | | polyhedral docs | Print the full SDK reference documentation |

Push Options

polyhedral push                # Patch bump (default)
polyhedral push --minor        # Minor version bump
polyhedral push --major --changelog "breaking changes description"
polyhedral push -f             # Skip confirmation prompt

Global Options

| Flag | Description | | ----------- | ----------------------------------------------------- | | --json | Output structured JSON (skips prompts, useful for CI) | | --version | Show CLI version | | --help | Show help |

Commands that modify data (push, pull, delete) prompt for confirmation. Use --force / -f to skip, or --json which implies --force.

Build Types

The CLI supports two build types, chosen during polyhedral init:

In-App (default)

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

polyhedral init my-sheet    # select "In-App"

External

For pre-built templates — plain HTML/JS, or output from a bundler like Vite or webpack. You control the full HTML document; the Polyhedral SDK scripts are automatically injected into <head> at render time.

JSX validation is skipped for external builds since the file isn't JSX. You'll see a "Skipping JSX validation (external build)" message during push, dev, and validate.

polyhedral init my-sheet    # select "External"

Use external when you want to:

• Use a framework like React, Vue, or Svelte with your own build step
• Write plain HTML/CSS/JS without JSX
• Bundle with Vite, webpack, or another tool
• Have full control over the document structure

How It Works

Templates are JSX files (in-app) or HTML files (external) using the Polyhedral SDK. The CLI wraps the REST API to manage templates from the terminal.

The dev command is the main workflow: it pushes your template, opens the preview page, and watches for file changes (including polyhedral.json). When you save, it validates locally and pushes automatically. The preview page uses realtime subscriptions, so it updates without a manual refresh.

Validation runs offline using Babel — no network connection or login required.

Docs

Full documentation at polyhedral.co/developers/cli.

License

MIT