npm package: @flickerdeck/flickerdeck-cli
Description: Command-line tools for working with Flicker Deck bundles.
Latest version: 0.6.0

# flickerdeck CLI

Command-line tools for working with Flicker Deck bundles.

## Prerequisites

- Node.js (LTS) v16 or newer. Download from [nodejs.org](https://nodejs.org/en/download).

Verify your version:

```bash
node -v
# v16.x or newer
```

## Install

Global (recommended):

```bash
npm install --global @flickerdeck/flickerdeck-cli
```

From this monorepo during development:

```bash
corepack yarn build
npm link
```

## Usage

```text
flickerdeck --help

Usage
  $ flickerdeck

Commands
  validate <path>          Validate a deck bundle directory
  plan <path>              Preview create/update plan for Strapi (no writes)
  apply <path>             Apply the plan to Strapi (writes). Generates audit log.
  apply --imgreplace --imgclean <path>  Apply with image upload/replace/cleanup

Options
  --report <file>          Write JSON report to file (default: <bundle>/reports/validate/validate-report-{timestamp}.json)
  --concurrency <number>   Max parallel writes for apply (default: 5)
  --imgreplace            Replace existing card images by uploading new media and remapping
  --imgclean              When replacing, delete previous media after successful remap
  --verbose               Show detailed logs during apply (deck, cards, media)
```

### Validate deck bundle

Validates a deck bundle directory on disk. Fails with non-zero exit code on invalid bundles.

```bash
flickerdeck validate ./path/to/bundle
# or custom output path
flickerdeck validate ./path/to/bundle --report ./some/where/report.json
```

Default report location (when --report is not provided):

```
<bundle>/reports/validate/validate-report-{timestamp}.json
```

Terminal output shows a concise summary and colorized error totals, for example:

```text
Bundle: ./input/rws
Counts: cards=78, images=78
Errors: deckRows=0, cardRows=0, structure=0
Full report: /absolute/path/to/bundle/reports/validate/validate-report-2025-01-01T00-00-00-000Z.json
Valid ✅
```

### Bundle layout

The CLI uses a **unified naming system** that keeps local files clean and standardized while automatically adding prefixes when uploading to Strapi.

```
bundle/
  deck.csv       # Deck metadata with required imagePrefix
  cards.csv      # Card data with clean UIDs
  cards/         # Card images with clean names
    00-the-fool.png
    01-the-magician.png
    swords-01.png
  deck/          # Standardized deck assets
    card-back.png
    deck-box-color.png
    deck-box-front.png
```

**Required fields in `deck.csv`:**

- title
- slug
- **imagePrefix** ⭐ (letters only, e.g., "rws", "tarot") - **REQUIRED**
- entitlementId
- author
- copyright
- description
- shortDescription
- deckBoxColor (hex, e.g. "#FFAA00")
- aiPrompt

**Required fields in `cards.csv`:**

- uid (clean format, e.g., "00-the-fool", "swords-01")
- title
- keywords
- description
- arcana ("major" or "minor")
- suit (required for minor arcana, empty for major)

**Local vs Strapi naming:**

| Component   | Local Bundle      | Uploaded to Strapi    |
| ----------- | ----------------- | --------------------- |
| Deck assets | `card-back.png`   | `rws-card-back.png`   |
| Card UIDs   | `00-the-fool`     | `rws-00-the-fool`     |
| Card images | `00-the-fool.png` | `rws-00-the-fool.png` |

> 💡 **See [BUNDLE-FORMAT.md](./BUNDLE-FORMAT.md) for a detailed, user-friendly guide.**

### Strapi plan/apply

Configuration can be provided via environment variables or a local config file placed next to the bundle:

```json
{
	"STRAPI_URL": "https://staging.example.com",
	"STRAPI_TOKEN": "<api-token>"
}
```

Supported filenames: `flickerdeck.config.json|yaml|yml`.

Plan (no writes):

```bash
flickerdeck plan ./path/to/bundle
```

Apply (writes to Strapi, generates audit log under `<bundle>/reports/apply`):

```bash
flickerdeck apply ./path/to/bundle --concurrency 8
```

Advanced apply options:

```bash
# Apply with verbose logging
flickerdeck apply ./path/to/bundle --verbose

# Force replace all images and clean up old ones
flickerdeck apply ./path/to/bundle --imgreplace --imgclean

# Apply with custom concurrency and image replacement
flickerdeck apply ./path/to/bundle --concurrency 3 --imgreplace --verbose
```