Wishboard CLI

CLI tool for creating beautiful PDF galleries from images for vision board printing.

Installation

npm i -g wishboard-cli

That's it! No additional dependencies required.

Quick Start

# Create PDF from current folder
wb 4 4 4

# From specific folder
wb ./photos 2 3 4

# Auto-scan subfolders (each folder = 1 page)
wb --depth 1 ./my-boards

Usage Modes

Mode 1: Manual Layout

Specify exactly how many images per page:

wb [folder] <images_per_page...> [options]

wb 1 2 3 4           # Page 1: 1 img, Page 2: 2 imgs, Page 3: 3 imgs, Page 4: 4 imgs
wb ./photos 4 4 4    # 3 pages with 4 images each
wb 9 -o collage.pdf  # 9 images on one page

Mode 2: Folder Scan (--depth)

Automatically create pages from folder structure:

wb --depth <n> [folder] [options]

Each folder with images becomes a separate PDF page. The number of images per page is determined automatically.

wb --depth 1              # Scan 1 level deep from current folder
wb --depth 2 ./boards     # Scan 2 levels deep
wb --depth 3 -o vision.pdf

Depth Example

wishboard/
├── goals/
│   ├── career.jpg
│   ├── health.jpg
│   └── family.jpg
├── travel/
│   ├── paris/
│   │   ├── 1.jpg
│   │   └── 2.jpg
│   ├── tokyo/
│   │   ├── 1.jpg
│   │   ├── 2.jpg
│   │   └── 3.jpg
│   └── beach.jpg        # image in travel/ folder
└── motivation/
    └── quotes.jpg

| Command | Result | |---------|--------| | wb --depth 1 wishboard | 3 pages: goals (3), travel (1), motivation (1) | | wb --depth 2 wishboard | 5 pages: goals (3), paris (2), tokyo (3), travel (1), motivation (1) |

Layout Modes (--smart)

Smart Layout (default, --smart=1)

Fills page creatively without empty cells:

┌─────────┬─────┐    ┌───────────────┐
│         │  2  │    │       1       │
│    1    ├─────┤    ├───────┬───────┤
│         │  3  │    │   2   │   3   │
└─────────┴─────┘    └───────┴───────┘
   3 images              3 images
  (portrait)           (landscape)

┌─────────┬────┬────┐
│         │  2 │  3 │
│    1    ├────┼────┤
│         │  4 │  5 │
└─────────┴────┴────┘
      5 images

Uniform Layout (--smart=0)

Simple equal distribution — all cells same size:

wb --smart=0 3           # 3 equal cells
wb -s 0 --depth 1        # Folder scan with uniform layout

Landscape images → portrait page, stacked vertically:

┌─────────────┐
│      1      │
├─────────────┤
│      2      │
├─────────────┤
│      3      │
└─────────────┘

Portrait images → landscape page, side by side:

┌────┬────┬────┐
│    │    │    │
│ 1  │ 2  │ 3  │
│    │    │    │
└────┴────┴────┘

Image Fit Modes (--fit)

Cover (default)

Fills entire cell, may crop edges:

wb 4 --fit cover
wb 4 -f cover

Contain

Fits inside cell, preserves full image (may have margins):

wb 4 --fit contain
wb 4 -f contain

All Options

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --output <file> | -o | Output PDF path | wishboard_TIMESTAMP.pdf | | --depth <n> | -d | Folder scan depth | 0 (disabled) | | --smart <0\|1> | -s | Layout mode | 1 (smart) | | --fit <mode> | -f | Image fit: cover or contain | cover | | --no-compress | | Higher quality, larger file | compressed | | --help | -h | Show help | | | --version | -V | Show version | |

Examples

# Basic usage
wb 4                           # 4 images on 1 page
wb 1 4 9                       # 3 pages: 1, 4, 9 images

# With options
wb 6 -f contain                # Contain mode
wb 4 4 4 -o boards.pdf         # Custom output name
wb 9 --no-compress             # High quality

# Folder scan
wb --depth 1                   # Each subfolder = page
wb -d 2 ./images               # 2 levels deep
wb -d 1 -s 0                   # Uniform layout
wb -d 2 -f contain -o out.pdf  # All options combined

Supported Formats

PNG, JPG, JPEG, GIF, BMP, TIFF, WEBP, HEIC, HEIF, AVIF

Features

• Zero Config — Just install and use, no Python or other dependencies
• Smart Layout — Creative space filling without empty cells
• Folder Scan — Auto-generate pages from folder structure
• Fit Modes — Cover (crop) or Contain (preserve)
• High Quality — A4 format at 300 DPI for crisp prints
• Apple Photos — Native HEIC/HEIF support
• Natural Sorting — Images sorted correctly (1.jpg, 2.jpg, 10.jpg)
• Fast — Powered by sharp for blazing fast image processing

How It Works

1. Scans folder(s) for images
2. Sorts in natural order (1.jpg, 2.jpg, 10.jpg)
3. Determines optimal page orientation per page
4. Applies smart or uniform layout
5. Scales images with cover/contain mode
6. Generates A4 PDF at 300 DPI

Requirements

• Node.js 18+

Development

git clone https://github.com/creative-ventures/wishboard-cli.git
cd wishboard-cli
npm install
npm run build

Author

Creative Ventures

License

MIT