npm package: @plotset/cli
Description: CLI tool for managing and publishing PlotSet templates
Author: PlotSet
Latest version: 1.0.5

# PlotSet CLI

A command-line interface tool for creating, managing, and publishing PlotSet data visualization templates.

## Installation

```bash
npm install -g @plotset/cli
# or
npm uninstall -g cli-plotset && npm install -g @plotset/cli
```

## Quick Start

```bash
# Login to PlotSet
plotset login

# Create a new template
plotset new

# Publish to staging
plotset publish

# Publish to production
plotset publish-production
```

## Commands

### Authentication

| Command | Description |
|---------|-------------|
| `plotset login` | Login to PlotSet production (plotset.com) |
| `plotset logout` | Logout from PlotSet production |
| `plotset login-stage` | Login to PlotSet staging (plotset.net) |
| `plotset logout-stage` | Logout from PlotSet staging |
| `plotset profile` | Show your profile information |

### Project Management

| Command | Description |
|---------|-------------|
| `plotset new` | Create a new PlotSet template project |
| `plotset add-test-files` | Add Cypress test files to the project |
| `plotset update-project` | Update project to latest template version |

### Publishing

| Command | Description |
|---------|-------------|
| `plotset publish` | Publish template to staging (plotset.net) |
| `plotset publish-production` | Publish template to production (plotset.com) |
| `plotset test-zip` | Test zip file generation without publishing |
| `plotset test-git` | Verify project is on required GitHub organization |

## Template Structure

When you create a new template with `plotset new`, it generates the following structure:

```
my-template/
├── src/
│   ├── css/
│   │   └── main.css          # Styles (auto-imported in HTML)
│   ├── js/
│   │   ├── index.js          # Main entry point
│   │   └── chart.js          # Chart implementation
│   ├── bindings.json         # Data bindings configuration
│   ├── data.csv              # Default template data
│   ├── index.html            # HTML template
│   ├── info.json             # Template metadata
│   ├── settings.json         # Template settings/configuration
│   └── thumbnail.png         # Template preview image
├── cypress/                  # Test files
├── package.json
└── plotset.json             # PlotSet deployment config
```

## Required Methods

Your template must implement these methods in `src/js/index.js`:

| Method | Description | Required |
|--------|-------------|----------|
| `init_handler` | Called on first load, data change, or binding change | ✓ |
| `change_config_handler` | Called when settings change | ✓ |
| `resizeHandler` | Called when iframe resizes | ✓ |
| `transformData` | Called to transform data before rendering | ✗ |

## Global Variables

These variables are available globally in your template:

- `data` - Current dataset
- `backupData` - Original dataset backup
- `config` - Current configuration/settings
- `oldConfig` - Previous configuration
- `col_rel` - Column relationship bindings
- `width` - Current width
- `height` - Current height

## Publishing Workflow

### Staging (Development)

```bash
plotset login-stage
plotset publish
```

Version updates are not required for staging.

### Production

```bash
plotset login
plotset publish-production
```

For production:
- Your project must be on `github.com/plotset-corp`
- You'll be prompted to select a version increment (patch/minor/major)
- First publish will create a new template
- Subsequent publishes will update the existing template

## Configuration Files

### `plotset.json`

Stores template IDs for different environments:

```json
{
  "templateId": 102,
  "stagingTemplateId": 45
}
```

### `src/info.json`

Template metadata:

```json
{
  "title": "My Chart Template",
  "author": "Your Name",
  "slug": "my-chart-template",
  "category": 1
}
```

## Development

### Prerequisites

- Node.js >= 18.0.0
- npm or yarn

### Setup

```bash
# Clone and install
git clone https://github.com/PlotSet/plotset-cli.git
cd plotset-cli
npm install

# Build
npm run build

# Development
npm run dev
```

### Project Structure

```
src/
├── api/           # API client and methods
├── commands/      # CLI command definitions
├── config/        # Configuration management
├── services/      # Business logic
├── types/         # TypeScript type definitions
├── utils/         # Utility functions
└── index.ts       # CLI entry point
```

## License

MIT © [PlotSet](https://plotset.com)