npm package: @playtagon/cli
Description: Playtagon CLI for uploading Spine assets
Latest version: 0.5.6

# @playtagon/cli

Command-line interface for uploading and managing Spine animation assets on the Playtagon platform.

## Installation

```bash
npm install -g @playtagon/cli
```

## Authentication

Login to your Playtagon account:

```bash
playtagon login
```

This opens your browser for secure authentication. After logging in, you can verify your session:

```bash
playtagon whoami
```

To logout:

```bash
playtagon logout
```

## Uploading Spine Assets

### Auto-Upload with File Watcher (Recommended)

Start watching a directory for new exports. Files will automatically upload when you export from Spine Editor:

```bash
playtagon spine watch ./exports --studio my-studio --game my-game
```

This command runs in the background and automatically uploads files whenever Spine creates a new export. Just keep it running in a terminal while you work.

**Options:**
- `--batch` - Enable batch mode for multiple skeletons sharing one atlas
- `--interval <seconds>` - Change check interval (default: 2 seconds)

Press `Ctrl+C` to stop watching.

### Manual Upload

Upload a Spine asset directory to a specific studio and game:

```bash
playtagon spine upload ./my-animation --studio my-studio --game my-game
```

### Validate Before Upload

Check your Spine files without uploading:

```bash
playtagon spine validate ./my-animation
```

### Dry Run

Test the upload process without actually uploading:

```bash
playtagon spine upload ./my-animation --studio my-studio --game my-game --dry-run
```

## Configuration

### Interactive Setup

Run the setup wizard to configure defaults:

```bash
playtagon setup
```

### Set Default Studio/Game

```bash
playtagon config set defaultStudio my-studio
playtagon config set defaultGame my-game
```

### View Current Config

```bash
playtagon config get defaultStudio
playtagon config list
```

## Spine Export Preset

Generate a recommended Spine export preset for consistency:

```bash
playtagon spine preset > playtagon-export.json
```

Import this file into Spine Editor for optimal export settings.

## Syncing Assets (for Developers)

Download approved Spine assets to your local project with TypeScript types and Storybook stories:

```bash
# Sync all approved assets
playtagon spine sync --studio my-studio --game my-game

# Sync to custom directory
playtagon spine sync -s my-studio -o ./src/assets/spine

# Sync specific assets only
playtagon spine sync --assets hero,villain,effects

# Preview what would be synced
playtagon spine sync --dry-run

# Force overwrite local changes
playtagon spine sync --force
```

### Generated Files

```
src/assets/spine/
├── hero/
│   ├── hero.skel           # Skeleton file
│   ├── hero.atlas          # Atlas file
│   ├── hero.png            # Texture(s)
│   ├── index.ts            # TypeScript types
│   └── hero.stories.ts     # Storybook story
├── villain/
│   └── ...
└── manifest.ts             # Re-exports all assets
```

### TypeScript Types

Generated `index.ts` provides full IntelliSense:

```typescript
import { hero } from './assets/spine/manifest';

// Typed animation names
hero.animations.idle;
hero.animations.walk;

// Animation durations (seconds)
hero.durations.idle;   // 1.5
hero.durations.walk;   // 0.8

// Skins and events
hero.skins.default;
hero.events.footstep;
```

### Incremental Sync

The CLI tracks synced assets in `.sync-manifest.json`. Subsequent syncs only download new or updated assets. Use `--force` to re-download everything.

## Commands

| Command | Description |
|---------|-------------|
| `playtagon login` | Authenticate with Playtagon |
| `playtagon logout` | Clear stored credentials |
| `playtagon whoami` | Show current user info |
| `playtagon setup` | Interactive setup wizard |
| `playtagon config` | Manage configuration |
| `playtagon spine upload` | Upload Spine assets (manual) |
| `playtagon spine watch` | Auto-upload on file changes (recommended) |
| `playtagon spine validate` | Validate Spine files |
| `playtagon spine preset` | Output export preset JSON |
| `playtagon spine sync` | Sync approved assets with codegen |

## Requirements

- Node.js 18 or higher
- Valid Playtagon account

## Support

For issues and feedback, contact [support@playtagon.com](mailto:support@playtagon.com)