appshot-cli 0.8.7 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/README.md +480 -15
  2. package/dist/cli.js +19 -5
  3. package/dist/cli.js.map +1 -1
  4. package/dist/commands/build.d.ts.map +1 -1
  5. package/dist/commands/build.js +16 -2
  6. package/dist/commands/build.js.map +1 -1
  7. package/dist/commands/preset.d.ts +5 -0
  8. package/dist/commands/preset.d.ts.map +1 -0
  9. package/dist/commands/preset.js +191 -0
  10. package/dist/commands/preset.js.map +1 -0
  11. package/dist/commands/quickstart.d.ts +3 -0
  12. package/dist/commands/quickstart.d.ts.map +1 -0
  13. package/dist/commands/quickstart.js +326 -0
  14. package/dist/commands/quickstart.js.map +1 -0
  15. package/dist/commands/style.d.ts.map +1 -1
  16. package/dist/commands/style.js +98 -0
  17. package/dist/commands/style.js.map +1 -1
  18. package/dist/commands/template.d.ts +3 -0
  19. package/dist/commands/template.d.ts.map +1 -0
  20. package/dist/commands/template.js +399 -0
  21. package/dist/commands/template.js.map +1 -0
  22. package/dist/core/compose.d.ts +16 -0
  23. package/dist/core/compose.d.ts.map +1 -1
  24. package/dist/core/compose.js +342 -83
  25. package/dist/core/compose.js.map +1 -1
  26. package/dist/services/doctor.js +1 -1
  27. package/dist/templates/registry.d.ts +73 -0
  28. package/dist/templates/registry.d.ts.map +1 -0
  29. package/dist/templates/registry.js +724 -0
  30. package/dist/templates/registry.js.map +1 -0
  31. package/dist/types.d.ts +15 -0
  32. package/dist/types.d.ts.map +1 -1
  33. package/dist/utils/validation.d.ts +36 -0
  34. package/dist/utils/validation.d.ts.map +1 -0
  35. package/dist/utils/validation.js +143 -0
  36. package/dist/utils/validation.js.map +1 -0
  37. package/package.json +3 -2
package/README.md CHANGED
@@ -2,19 +2,31 @@
2
2
 
3
3
  > **AI-First CLI for App Store Screenshots** - Generate beautiful, localized screenshots with device frames, gradients, and captions.
4
4
 
5
+ 🌐 https://appshot.sh
6
+
5
7
  [![CI](https://github.com/chrisvanbuskirk/appshot/actions/workflows/ci.yml/badge.svg)](https://github.com/chrisvanbuskirk/appshot/actions/workflows/ci.yml)
6
8
  [![npm version](https://badge.fury.io/js/appshot-cli.svg)](https://www.npmjs.com/package/appshot-cli)
7
9
  [![npm downloads](https://img.shields.io/npm/dm/appshot-cli.svg)](https://www.npmjs.com/package/appshot-cli)
8
10
  [![Node.js Version](https://img.shields.io/node/v/appshot-cli.svg)](https://nodejs.org)
9
11
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
10
12
 
11
- 🆕 **Version 0.8.6** - **Background Images** - Replace gradients with custom static images, auto-detection, and dimension validation!
12
-
13
- > ⚠️ **NEW in v0.8.6**: Use custom background images instead of gradients! Auto-detects `background.png` in device folders, supports multiple fit modes, and validates dimensions against App Store specs.
14
-
15
- > ⚠️ **BREAKING CHANGE in v0.4.0**: Output structure now always uses language subdirectories.
16
- > Single language builds now output to `final/device/lang/` instead of `final/device/`.
17
- > Run `appshot migrate --output-structure` to update existing projects.
13
+ 🆕 **Version 0.9.0** - **Professional Template System & Enhanced Positioning**
14
+ - **Quick Start**: New `appshot quickstart` command for instant setup with templates
15
+ - **Templates**: 8 professional templates (modern, minimal, bold, elegant, showcase, playful, corporate, nerdy)
16
+ - **One Command Setup**: Apply complete visual styles with `appshot template <name>`
17
+ - **Smart Defaults**: Each template includes optimized settings for all devices
18
+ - **Caption Integration**: Templates can include captions directly with `--caption`
19
+ - **Vertical Alignment**: Pin caption text to top or center within the caption box
20
+ - **Side Margins**: Control caption box width with `sideMargin` (unified wrapping calculation)
21
+ - **Outer Margins**: Add spacing with `marginTop`/`marginBottom` for better visual balance
22
+ - **Apple Watch Fix**: Resolved positioning bug allowing proper framePosition control
23
+ - **Exact Width Parity**: Caption wrapping now identical between preview and final render
24
+ - **Template Samples Overhaul**: Local-only gallery with consolidated generator. Run `npm run samples` to regenerate all 8 presets across iPhone, iPad, Watch, and Mac. Gallery assets now live under `template-samples/gallery/` and the samples page matches the appshot.sh look (including ASCII header).
25
+
26
+ > Note on layout changes (0.9.0): This release refines caption placement rules.
27
+ > - Overlay captions are anchored by the bottom of the entire caption box (padding/border included), and `0` values are respected.
28
+ > - Above/Below captions enforce a minimum optical clearance from the device and stay fully on‑canvas. In pathological cases where device + caption don’t fit, the engine adapts placement so order is preserved.
29
+ > - Visual results may differ compared to 0.8.x when captions were near device edges. Adjust `marginTop` (below) / `marginBottom` (above) or `frameScale`/`framePosition` for fine‑tuning.
18
30
 
19
31
  ## 📖 Table of Contents
20
32
 
@@ -24,12 +36,14 @@
24
36
  - [Prerequisites](#prerequisites)
25
37
  - [Installation](#installation)
26
38
  - [Your First Screenshot](#your-first-screenshot)
39
+ - [Claude Code Integration](#-claude-code-integration)
27
40
  - [Core Concepts](#-core-concepts)
28
41
  - [Visual Customization](#-visual-customization)
29
42
  - [Gradient System](#gradient-system)
30
43
  - [Font System](#font-system)
31
44
  - [Device Frames](#device-frames)
32
45
  - [Caption System](#caption-system)
46
+ - [Style System Guide](#style-system-guide)
33
47
  - [Localization & Translation](#-localization--translation)
34
48
  - [Device Support](#-device-support)
35
49
  - [Command Reference](#-command-reference)
@@ -45,6 +59,8 @@
45
59
 
46
60
  Appshot is the only **agent-first CLI tool** designed for automated App Store screenshot generation. Built for LLM agents, CI/CD pipelines, and developers who value automation over GUIs.
47
61
 
62
+ **NEW in v0.9.0**: One-line preset commands! Generate professional screenshots instantly with `appshot preset bold --caption "Amazing App" --devices iphone,watch`
63
+
48
64
  ### Key Differentiators
49
65
 
50
66
  - 🤖 **Agent-First Design** - JSON outputs, predictable commands, no interactive prompts in automation mode
@@ -97,9 +113,28 @@ appshot --version
97
113
 
98
114
  > **Note**: The package is called `appshot-cli` on NPM, but the command is `appshot`
99
115
 
100
- ### Your First Screenshot
116
+ ### Your First Screenshot - Two Ways
117
+
118
+ #### Option 1: Quick Start with Templates (NEW! 🎨)
119
+
120
+ The fastest way to get professional screenshots:
121
+
122
+ ```bash
123
+ # One command interactive setup
124
+ appshot quickstart
125
+
126
+ # Or apply a specific template
127
+ appshot template modern --caption "Your Amazing App"
128
+
129
+ # Build your screenshots
130
+ appshot build
131
+
132
+ # ✨ Professional screenshots ready in seconds!
133
+ ```
134
+
135
+ #### Option 2: Traditional Step-by-Step
101
136
 
102
- Create App Store-ready screenshots in 5 simple steps:
137
+ Full control over every aspect:
103
138
 
104
139
  ```bash
105
140
  # 1. Initialize your project
@@ -166,6 +201,82 @@ final/
166
201
  └── dashboard.png # 2048×2732 iPad Pro screenshot
167
202
  ```
168
203
 
204
+ ## 🤖 Claude Code Integration
205
+
206
+ Appshot includes comprehensive [Claude Code](https://claude.ai/code) slash commands for AI-assisted screenshot generation. See the [complete commands documentation](./commands/README.md) for detailed examples and workflows.
207
+
208
+ ### Available Commands
209
+
210
+ Appshot provides specialized commands for different tasks:
211
+
212
+ - `/appshot-init` - Initialize and configure new projects
213
+ - `/appshot-preset` - One-line preset commands for instant screenshots
214
+ - `/appshot-style` - Apply gradients, fonts, and visual styling
215
+ - `/appshot-caption` - Manage captions and translations
216
+ - `/appshot-build` - Build screenshots with troubleshooting
217
+ - `/appshot-config` - Complete configuration reference
218
+ - `/appshot-quick` - Quick reference for common tasks
219
+
220
+ ### Quick Installation
221
+
222
+ ```bash
223
+ # If you have AppShot source code
224
+ cd appshot
225
+ ./commands/install.sh
226
+
227
+ # If installed via npm
228
+ cd node_modules/appshot-cli
229
+ ./commands/install.sh
230
+
231
+ # Manual installation
232
+ mkdir -p ~/.claude/commands
233
+ ln -sf "$(pwd)/commands"/*.md ~/.claude/commands/
234
+ ```
235
+
236
+ ### How It Works
237
+
238
+ When you use a command like `/appshot-style ocean iphone` in Claude Code:
239
+
240
+ 1. Claude receives complete documentation for that specific task
241
+ 2. All necessary configurations and examples are provided inline
242
+ 3. No need to search documentation or run help commands
243
+ 4. Claude can immediately execute the appropriate AppShot CLI commands
244
+
245
+ ### Example Conversation
246
+
247
+ ```
248
+ User: I need to add Apple Watch support to my existing iPhone project
249
+
250
+ Claude: I'll help you add Apple Watch to your project. Let me use /appshot-config
251
+ to show you the exact configuration needed.
252
+
253
+ Add this to your .appshot/config.json under "devices":
254
+
255
+ "watch": {
256
+ "input": "./screenshots/watch",
257
+ "resolution": "410x502",
258
+ "autoFrame": true
259
+ }
260
+
261
+ Note: Apple Watch has special caption handling - uses 2-line wrapping
262
+ and smaller font size (36px max) for the smaller screen.
263
+ ```
264
+
265
+ ### Features for AI Agents
266
+
267
+ - **Self-Contained**: Each command includes all necessary information
268
+ - **No Lookups Required**: Commands work without external documentation
269
+ - **Agent-Friendly**: Non-interactive commands for full automation
270
+ - **Complete Examples**: Real-world configurations and workflows
271
+ - **Troubleshooting**: Built-in solutions for common issues
272
+
273
+ ### Learn More
274
+
275
+ For complete documentation, examples, and advanced workflows, see:
276
+ - 📚 [Commands Documentation](./commands/README.md) - Full guide with examples
277
+ - 📁 [Commands Directory](./commands/) - Individual command files
278
+ - 🛠️ [Installation Script](./commands/install.sh) - Automated setup
279
+
169
280
  ## 📘 Core Concepts
170
281
 
171
282
  ### Project Structure
@@ -246,6 +357,132 @@ All settings are stored in `.appshot/config.json`:
246
357
 
247
358
  ## 🎨 Visual Customization
248
359
 
360
+ ### Template System (NEW! 🚀)
361
+
362
+ Appshot now includes professional screenshot templates that configure everything with a single command. Each template includes carefully designed backgrounds, device positioning, caption styling, and device-specific optimizations.
363
+
364
+ #### Quick Start with Templates
365
+
366
+ ```bash
367
+ # Interactive template selection
368
+ appshot quickstart
369
+
370
+ # Apply a specific template
371
+ appshot template modern
372
+
373
+ # Apply template with caption
374
+ appshot template minimal --caption "Beautiful & Simple"
375
+
376
+ # Preview template settings
377
+ appshot template --preview bold
378
+
379
+ # List all templates
380
+ appshot template --list
381
+ ```
382
+
383
+ #### Available Templates
384
+
385
+ 📸 **[View Template Gallery](./template-samples/index.html)** - See visual examples of all templates
386
+
387
+ | Template | Description | Best For |
388
+ |----------|-------------|----------|
389
+ | **modern** | Vibrant gradient with floating device and clean captions | Most apps, eye-catching |
390
+ | **minimal** | Soft pastel background with elegant typography | Clean, simple apps |
391
+ | **bold** | Dark dramatic gradient with overlay captions | Gaming, entertainment |
392
+ | **elegant** | Sophisticated monochrome design | Professional, business |
393
+ | **showcase** | Auto-detects custom backgrounds, partial frames | Apps with branded assets |
394
+ | **playful** | Bright, fun gradients | Games, kids apps |
395
+ | **corporate** | Clean, professional look | Business, productivity |
396
+ | **nerdy** | JetBrains Mono typography with OSS grid background | Developer tools |
397
+
398
+ ![Template Gallery](./template-samples/gallery/template-gallery.png)
399
+
400
+ ##### Rebuild the Gallery Locally
401
+
402
+ ```bash
403
+ # From repo root
404
+ npm run samples
405
+ ```
406
+
407
+ This generates:
408
+ - Device samples: `template-samples/{iphone|ipad|watch|mac}/<template>-<device>.png`
409
+ - Gallery cards: `template-samples/gallery/*-sample.png`
410
+ - Combined image: `template-samples/gallery/template-gallery.png`
411
+
412
+ #### Template Features
413
+
414
+ Each template automatically configures:
415
+ - **Background**: Gradient colors and direction or image settings
416
+ - **Device Scale**: Optimal size for visual balance (70-110%)
417
+ - **Device Position**: Top, center, bottom, or custom percentage
418
+ - **Caption Style**: Font, size, color, and position
419
+ - **Caption Background**: Optional semi-transparent background with padding
420
+ - **Caption Border**: Optional border with customizable radius
421
+ - **Partial Frames**: Modern look with cut-off device bottoms
422
+ - **Device Overrides**: Optimized settings for watch, iPad, etc.
423
+
424
+ #### Template Examples
425
+
426
+ ```bash
427
+ # Modern Template - Perfect for most apps
428
+ appshot template modern
429
+ # → Vibrant diagonal gradient (#667eea → #764ba2 → #f093fb)
430
+ # → 85% device scale, centered
431
+ # → White captions with dark semi-transparent background
432
+
433
+ # Minimal Template - Clean and simple
434
+ appshot template minimal
435
+ # → Soft pastel gradient (#ffecd2 → #fcb69f)
436
+ # → 75% device scale, lower position
437
+ # → Dark text on light background
438
+
439
+ # Bold Template - Make a statement
440
+ appshot template bold
441
+ # → Dark gradient (#0f0c29 → #302b63 → #24243e)
442
+ # → 110% device scale with partial frame
443
+ # → Large overlay captions with border
444
+
445
+ # Showcase Template - Feature your backgrounds
446
+ appshot template showcase
447
+ # → Auto-detects background.png in device folders
448
+ # → 90% scale with 25% partial frame
449
+ # → Glass-morphism caption effect
450
+ ```
451
+
452
+ #### Customizing Templates
453
+
454
+ Templates provide a starting point that you can further customize:
455
+
456
+ ```bash
457
+ # 1. Apply a template
458
+ appshot template modern
459
+
460
+ # 2. Fine-tune specific settings
461
+ appshot style --device iphone # Adjust positioning
462
+ appshot fonts --set "Poppins Bold" # Change font
463
+ appshot caption --device iphone # Update captions
464
+
465
+ # 3. Build with your customizations
466
+ appshot build
467
+ ```
468
+
469
+ #### Creating Consistent Screenshots
470
+
471
+ Templates ensure consistency across all your screenshots:
472
+
473
+ ```json
474
+ // After applying a template, all devices share:
475
+ {
476
+ "background": { /* Same gradient/image */ },
477
+ "caption": { /* Same font and styling */ },
478
+ "devices": {
479
+ "iphone": { /* Optimized for iPhone */ },
480
+ "ipad": { /* Optimized for iPad */ },
481
+ "watch": { /* Special watch handling */ }
482
+ }
483
+ }
484
+ ```
485
+
249
486
  ### Gradient System
250
487
 
251
488
  Appshot includes 24+ professional gradient presets organized by category:
@@ -289,7 +526,7 @@ appshot gradients --sample
289
526
  }
290
527
  ```
291
528
 
292
- ### Background System (NEW in v0.8.6)
529
+ ### Background System
293
530
 
294
531
  Replace gradients with custom static background images for a unique, branded look. Appshot supports automatic detection, multiple formats, and intelligent scaling.
295
532
 
@@ -592,6 +829,79 @@ Create modern App Store screenshots with cut-off device frames:
592
829
  }
593
830
  ```
594
831
 
832
+ #### Frame Positioning System
833
+
834
+ **Important**: The `framePosition` value (0-100) behaves differently depending on your caption positioning mode.
835
+
836
+ ##### Relative vs Absolute Positioning
837
+
838
+ When using `captionPosition: "above"` or `"below"`:
839
+ - **Frame positioning is RELATIVE to the remaining space** after accounting for the caption
840
+ - `framePosition: 0` = Top of available space (immediately after/before caption)
841
+ - `framePosition: 50` = Center of remaining space
842
+ - `framePosition: 100` = Bottom of available space
843
+
844
+ When using `captionPosition: "overlay"`:
845
+ - **Frame positioning is ABSOLUTE to the entire canvas**
846
+ - `framePosition: 0` = Top of canvas (pixel 0)
847
+ - `framePosition: 50` = Center of entire canvas
848
+ - `framePosition: 100` = Bottom of canvas
849
+
850
+ ##### Visual Examples
851
+
852
+ ```json
853
+ // Example 1: Caption above with framePosition: 0
854
+ {
855
+ "devices": {
856
+ "iphone": {
857
+ "captionPosition": "above",
858
+ "framePosition": 0 // Device starts right after caption
859
+ }
860
+ }
861
+ }
862
+ // Result: [Caption] then [Device at top of remaining space]
863
+
864
+ // Example 2: Caption overlay with framePosition: 0
865
+ {
866
+ "devices": {
867
+ "iphone": {
868
+ "captionPosition": "overlay",
869
+ "framePosition": 0 // Device at absolute top
870
+ }
871
+ }
872
+ }
873
+ // Result: [Device at canvas top] with [Caption overlaid at bottom]
874
+ ```
875
+
876
+ ##### The Math Behind Positioning
877
+
878
+ For **"above" mode**, the device position is calculated as:
879
+ ```
880
+ deviceTop = topMargin + captionHeight + (availableSpace * framePosition/100)
881
+ where availableSpace = canvasHeight - topMargin - captionHeight - bottomMargin - deviceHeight
882
+ ```
883
+
884
+ For **"overlay" mode**, the device position is calculated as:
885
+ ```
886
+ deviceTop = availableSpace * (framePosition/100)
887
+ where availableSpace = canvasHeight - bottomMargin - deviceHeight
888
+ ```
889
+
890
+ ##### Practical Implications
891
+
892
+ 1. **Same framePosition, Different Results**: A `framePosition: 0` will place the device at different absolute positions:
893
+ - With `above` caption: Device starts after the caption (e.g., at pixel 198)
894
+ - With `overlay` caption: Device starts at the top (pixel 0)
895
+
896
+ 2. **Caption Height Affects Layout**: In `above`/`below` modes, varying caption lengths change the available space, affecting all frame positions. Use `overlay` mode for consistent device positioning across screenshots with different caption lengths.
897
+
898
+ 3. **Best Practices**:
899
+ - Use `above`/`below` for guaranteed caption-device separation
900
+ - Use `overlay` for consistent device positioning across all screenshots
901
+ - Set fixed caption heights (`minHeight`/`maxHeight`) for uniform layouts
902
+
903
+ 📚 **[Visual Preset Showcase](./positioning-guide/preset-showcase.html)** - Interactive visual guide showing all available preset templates and their styles
904
+
595
905
  ### Caption System
596
906
 
597
907
  #### Dynamic Caption Box
@@ -634,7 +944,7 @@ appshot style --device iphone
634
944
  }
635
945
  ```
636
946
 
637
- #### Caption Styling (New in v0.7.0)
947
+ #### Caption Styling (Enhanced in v0.8.7)
638
948
 
639
949
  Create professional captions with customizable backgrounds and borders:
640
950
 
@@ -650,7 +960,7 @@ Create professional captions with customizable backgrounds and borders:
650
960
  "border": {
651
961
  "color": "#FFFFFF", // Border color (hex)
652
962
  "width": 2, // Border thickness (1-10)
653
- "radius": 12 // Rounded corners (0-30)
963
+ "radius": 12 // Rounded corners (0-30); used for background too
654
964
  }
655
965
  }
656
966
  }
@@ -661,6 +971,8 @@ Create professional captions with customizable backgrounds and borders:
661
971
  - **Flexible positioning** - Works with above, below, and overlay positions
662
972
  - **Device-specific overrides** - Customize styling per device type
663
973
  - **Professional appearance** - Rounded corners and padding for polished look
974
+ - **Vertical anchoring (NEW)** - Align caption text to top or center of the box
975
+ - **Unified side margins (NEW)** - Control caption box width with `caption.background.sideMargin`
664
976
 
665
977
  **Interactive Configuration:**
666
978
  ```bash
@@ -669,6 +981,8 @@ appshot style --device iphone
669
981
  # → Choose caption position (above/below/overlay)
670
982
  # → Configure background color and opacity
671
983
  # → Set border color, width, and radius
984
+ # → Set vertical alignment (top/center)
985
+ # → Set side margin, min/max height, max lines
672
986
  ```
673
987
 
674
988
  **Examples:**
@@ -698,12 +1012,44 @@ appshot style --device iphone
698
1012
  "background": {
699
1013
  "color": "#FF5733",
700
1014
  "opacity": 0.6,
701
- "padding": 25
1015
+ "padding": 25,
1016
+ "sideMargin": 24
1017
+ }
1018
+ }
1019
+ }
1020
+ ```
1021
+
1022
+ #### Fixed vs Adaptive Caption Height
1023
+
1024
+ ```json
1025
+ {
1026
+ "caption": {
1027
+ "position": "above",
1028
+ "box": {
1029
+ "autoSize": false, // Fixed height banner
1030
+ "minHeight": 320,
1031
+ "maxHeight": 320,
1032
+ "verticalAlign": "top" // Pin text to top of banner
702
1033
  }
703
1034
  }
704
1035
  }
705
1036
  ```
706
1037
 
1038
+ - Set `autoSize: true` plus `minHeight`/`maxHeight` clamps for adaptive banners.
1039
+ - Use `verticalAlign: 'top'` to avoid recenters when height changes.
1040
+
1041
+ ### Preset Templates Guide
1042
+
1043
+ An interactive showcase of all available preset templates is available at `positioning-guide/preset-showcase.html`.
1044
+
1045
+ - Visual preview of all 7 professional templates (modern, minimal, bold, elegant, showcase, playful, corporate)
1046
+ - Side-by-side comparison across iPhone, iPad, Mac, and Watch devices
1047
+ - Shows gradient backgrounds, device positioning, and caption styles
1048
+ - Helps you choose the perfect template for your app's style
1049
+ - One-line command examples for each preset
1050
+
1051
+ Open the file in a browser to explore all available templates before applying them via `appshot preset` or `appshot template`.
1052
+
707
1053
  #### Caption Autocomplete
708
1054
 
709
1055
  The caption command includes intelligent autocomplete:
@@ -859,6 +1205,125 @@ appshot validate --fix
859
1205
 
860
1206
  ## 📝 Command Reference
861
1207
 
1208
+ ### `appshot quickstart` (NEW!)
1209
+
1210
+ Get started with App Store screenshots in seconds with interactive setup.
1211
+
1212
+ ```bash
1213
+ appshot quickstart [options]
1214
+ ```
1215
+
1216
+ **Options:**
1217
+ - `--template <id>` - Template to use (default: modern)
1218
+ - `--caption <text>` - Main caption for screenshots
1219
+ - `--no-interactive` - Skip interactive prompts
1220
+ - `--force` - Overwrite existing configuration
1221
+
1222
+ **What it does:**
1223
+ 1. Creates project structure
1224
+ 2. Applies professional template
1225
+ 3. Sets up example captions
1226
+ 4. Shows next steps
1227
+
1228
+ **Examples:**
1229
+ ```bash
1230
+ # Interactive setup
1231
+ appshot quickstart
1232
+
1233
+ # Quick setup with template
1234
+ appshot quickstart --template minimal --caption "My App"
1235
+
1236
+ # Non-interactive
1237
+ appshot quickstart --template bold --no-interactive
1238
+ ```
1239
+
1240
+ ### `appshot template` (NEW!)
1241
+
1242
+ Apply professional screenshot templates for instant visual styling.
1243
+
1244
+ ```bash
1245
+ appshot template [template] [options]
1246
+ ```
1247
+
1248
+ **Arguments:**
1249
+ - `[template]` - Template ID (modern, minimal, bold, elegant, showcase, playful, corporate)
1250
+
1251
+ **Options:**
1252
+ - `--list` - List all available templates
1253
+ - `--preview <id>` - Preview template configuration
1254
+ - `--caption <text>` - Add caption to all screenshots
1255
+ - `--device <name>` - Apply to specific device only
1256
+ - `--no-backup` - Skip config backup
1257
+ - `--dry-run` - Preview without applying
1258
+
1259
+ **Examples:**
1260
+ ```bash
1261
+ # List templates
1262
+ appshot template --list
1263
+
1264
+ # Apply template
1265
+ appshot template modern
1266
+
1267
+ # With caption
1268
+ appshot template minimal --caption "Beautiful App"
1269
+
1270
+ # Preview settings
1271
+ appshot template --preview bold
1272
+
1273
+ # Device-specific
1274
+ appshot template elegant --device iphone
1275
+ ```
1276
+
1277
+ ### `appshot preset` (NEW!)
1278
+
1279
+ Ultra-simple one-line commands to generate App Store screenshots with professional templates.
1280
+
1281
+ ```bash
1282
+ appshot preset <preset-name> [options]
1283
+ ```
1284
+
1285
+ **Arguments:**
1286
+ - `<preset-name>` - Template to use (modern, bold, minimal, elegant, showcase, playful, corporate)
1287
+
1288
+ **Options:**
1289
+ - `-c, --caption <text>` - Add caption to all screenshots
1290
+ - `-d, --devices <list>` - Comma-separated device list
1291
+ - `-l, --langs <list>` - Comma-separated language codes
1292
+ - `-o, --output <path>` - Output directory (default: ./final)
1293
+ - `--dry-run` - Preview without building
1294
+ - `-v, --verbose` - Show detailed output
1295
+
1296
+ **Examples:**
1297
+ ```bash
1298
+ # Quick professional screenshots
1299
+ appshot preset modern --caption "Amazing Features"
1300
+
1301
+ # Multiple devices
1302
+ appshot preset bold --devices iphone,ipad,watch
1303
+
1304
+ # Multiple languages
1305
+ appshot preset minimal --langs en,es,fr,de
1306
+
1307
+ # Custom output
1308
+ appshot preset elegant --output ./marketing/screenshots
1309
+
1310
+ # Preview mode
1311
+ appshot preset corporate --dry-run
1312
+
1313
+ # Full example
1314
+ appshot preset showcase \
1315
+ --caption "Summer Sale!" \
1316
+ --devices iphone,ipad \
1317
+ --langs en,es,fr \
1318
+ --output ./app-store-assets
1319
+ ```
1320
+
1321
+ **What it does:**
1322
+ 1. Applies professional template (gradient, positioning, styling)
1323
+ 2. Adds caption to first screenshot if provided
1324
+ 3. Builds screenshots for specified devices and languages
1325
+ 4. All in one command - perfect for CI/CD!
1326
+
862
1327
  ### `appshot build`
863
1328
 
864
1329
  Generate final screenshots with frames, gradients, and captions.
@@ -2202,10 +2667,10 @@ For security vulnerabilities, please see [SECURITY.md](SECURITY.md).
2202
2667
  ### NPM Package
2203
2668
 
2204
2669
  - 📦 [appshot-cli on NPM](https://www.npmjs.com/package/appshot-cli)
2205
- - 🔄 Latest version: 0.8.6
2670
+ - 🔄 Latest version: 0.9.0
2206
2671
 
2207
2672
  ---
2208
2673
 
2209
2674
  <div align="center">
2210
2675
  Built with ❤️ for developers and AI agents who automate everything.
2211
- </div>
2676
+ </div>
package/dist/cli.js CHANGED
@@ -21,10 +21,21 @@ import deviceCmd from './commands/device.js';
21
21
  import watchCmd from './commands/watch.js';
22
22
  import unwatchCmd from './commands/unwatch.js';
23
23
  import watchStatusCmd from './commands/watch-status.js';
24
+ import templateCmd from './commands/template.js';
25
+ import quickstartCmd from './commands/quickstart.js';
26
+ import presetCmd from './commands/preset.js';
24
27
  const program = new Command();
28
+ const logo = String.raw ` _ _ _
29
+ / \ _ __ _ __ ___| |__ ___ | |_
30
+ / _ \ | '_ \| '_ \/ __| '_ \ / _ \| __|
31
+ / ___ \| |_) | |_) \__ \ | | | (_) | |_
32
+ /_/ \_\ .__/| .__/|___/_| |_|\___/ \__|
33
+ |_| |_| `;
25
34
  program
26
35
  .name('appshot')
27
- .description(`Generate App Store–ready screenshots with frames, backgrounds, and captions.
36
+ .description(`${pc.cyan(logo)}
37
+
38
+ Generate App Store–ready screenshots with frames, backgrounds, and captions.
28
39
 
29
40
  ${pc.bold('Features:')}
30
41
  • Auto-detects portrait/landscape orientation
@@ -37,10 +48,10 @@ ${pc.bold('Features:')}
37
48
  • Device capture from simulators/physical devices (macOS)
38
49
 
39
50
  ${pc.bold('Quick Start:')}
40
- $ appshot init # Initialize project
51
+ $ appshot quickstart # Interactive setup with templates
52
+ $ appshot template modern # Apply professional template
41
53
  $ appshot caption --device iphone # Add captions
42
- $ appshot frame screenshot.png # Apply device frame only
43
- $ appshot build # Generate full screenshots
54
+ $ appshot build # Generate final screenshots
44
55
 
45
56
  ${pc.bold('Common Workflows:')}
46
57
  $ appshot fonts --set "Poppins Italic" # Set italic font
@@ -53,7 +64,7 @@ ${pc.bold('Common Workflows:')}
53
64
  $ appshot watch start --process # Auto-process new screenshots` : ''}
54
65
 
55
66
  ${pc.dim('Docs: https://github.com/chrisvanbuskirk/appshot')}`)
56
- .version('0.8.7')
67
+ .version('0.9.0')
57
68
  .addHelpText('after', `\n${pc.bold('Environment Variables:')}
58
69
  OPENAI_API_KEY API key for translation features
59
70
  APPSHOT_DISABLE_FONT_SCAN Skip system font detection (CI optimization)
@@ -64,7 +75,10 @@ ${pc.bold('Configuration Files:')}
64
75
  .appshot/caption-history.json Autocomplete history
65
76
 
66
77
  ${pc.dim('Run \'appshot <command> --help\' for command details.')}`);
78
+ program.addCommand(quickstartCmd());
67
79
  program.addCommand(initCmd());
80
+ program.addCommand(templateCmd());
81
+ program.addCommand(presetCmd());
68
82
  program.addCommand(captionCmd());
69
83
  program.addCommand(styleCmd());
70
84
  program.addCommand(gradientsCmd());
package/dist/cli.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
@@ -1 +1 @@
1
- {"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,MAAM,CAAC,OAAO,UAAU,QAAQ,YA6V/B"}
1
+ {"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,MAAM,CAAC,OAAO,UAAU,QAAQ,YA8W/B"}