flickerdeck CLI

Command-line tools for working with Flicker Deck bundles.

Prerequisites

• Node.js (LTS) v16 or newer. Download from nodejs.org.

Verify your version:

node -v
# v16.x or newer

Install

Global (recommended):

npm install --global @flickerdeck/flickerdeck-cli

From this monorepo during development:

corepack yarn build
npm link

Usage

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.

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:

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 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:

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

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

Plan (no writes):

flickerdeck plan ./path/to/bundle

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

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

Advanced apply options:

# 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