#!/bin/bash
# shotkit — App Store screenshot pipeline CLI
# Usage: shotkit <command> [options]
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
VERSION="2.2.0"
# Prefer the isolated venv created by install_deps.sh; fall back to the
# python3 on PATH (which the Homebrew wrapper points at libexec/vendor).
if [ -x "${SHOTKIT_HOME:-$HOME/.shotkit}/venv/bin/python3" ]; then
PYTHON="${SHOTKIT_HOME:-$HOME/.shotkit}/venv/bin/python3"
else
PYTHON="python3"
fi
usage() {
cat <<EOF
shotkit $VERSION — App Store screenshot pipeline
Usage:
shotkit <command> [options]
Capture & Generate:
capture Automated Simulator capture (boot, launch, deep link, screenshot)
generate Composite styled screenshots with text overlays
screenshots Full pipeline: capture + generate + validate in one command
validate Check output against App Store Connect requirements
App Store Connect:
init Connect to App Store Connect and configure your project
apps List your apps from App Store Connect
download Download existing screenshots from App Store Connect
upload Upload screenshots to App Store Connect
update Replace existing screenshots on App Store Connect
Utilities:
doctor Preflight check: Python deps, Xcode, Simulator, ASC config
palettes List available trending color palettes
frame-colors List available device frame colors
install-deps Install Python + Pillow + PyJWT dependencies (isolated venv)
Examples:
shotkit doctor
shotkit init
shotkit capture --bundle-id com.app.id --deeplinks "myapp://home,myapp://detail"
shotkit generate --app-name "MyApp" --captures ./raw --template trending --frame device
shotkit generate --app-name "MyApp" --captures ./raw --template bold --frame device --frame-color black-titanium
shotkit screenshots --bundle-id com.app.id --template trending --palette aurora
shotkit screenshots --bundle-id com.app.id --template trending --report ./run.json
shotkit upload --dir ./screenshots-output
Environment:
SHOTKIT_HOME Override the shotkit home dir (default: \$HOME/.shotkit)
SHOTKIT_LEGACY_INSTALL=1 Force install-deps to use system Python instead of a venv
Run 'shotkit <command> --help' for command-specific options.
EOF
}
if [ $# -eq 0 ]; then
usage
exit 0
fi
COMMAND="$1"
shift
case "$COMMAND" in
capture)
exec bash "$SCRIPT_DIR/auto_capture.sh" "$@"
;;
generate)
exec "$PYTHON" "$SCRIPT_DIR/generate_screenshots.py" "$@"
;;
validate)
exec "$PYTHON" "$SCRIPT_DIR/validate_output.py" "$@"
;;
doctor)
exec "$PYTHON" "$SCRIPT_DIR/doctor.py" "$@"
;;
init)
exec "$PYTHON" "$SCRIPT_DIR/asc_init.py" "$@"
;;
apps)
"$PYTHON" -c "
import sys; sys.path.insert(0, '$SCRIPT_DIR')
from asc_api import AppStoreConnectClient, load_config
config = load_config()
if not config:
print('Error: No .shotkit.json found. Run: shotkit init')
sys.exit(1)
client = AppStoreConnectClient(config['key_id'], config['issuer_id'], config['private_key_path'])
apps = client.list_apps()
print()
print('Your Apps')
print('=' * 60)
for a in apps:
print(f\" {a['name']:30s} {a['bundle_id']}\")
print(f\" {'':30s} ID: {a['id']}\")
print()
" "$@"
;;
download)
exec "$PYTHON" "$SCRIPT_DIR/asc_download.py" "$@"
;;
upload)
exec "$PYTHON" "$SCRIPT_DIR/asc_upload.py" "$@"
;;
update)
"$PYTHON" -c "
import sys; sys.path.insert(0, '$SCRIPT_DIR')
from asc_upload import main_update
main_update()
" "$@"
;;
screenshots)
# Full pipeline: capture + generate + validate
echo ""
echo "Shotkit — Full Screenshot Pipeline"
echo "==================================="
echo ""
# Parse flags for the combined command
BUNDLE_ID=""
TEMPLATE="trending"
APP_NAME=""
CAPTURES_DIR="./raw-captures"
OUTPUT_DIR="./screenshots-output"
COPY_FILE=""
DEVICES_SIM="iPhone 16 Pro Max"
DEVICES_GEN="iphone-6.9"
LOCALES="en-US"
DEEPLINKS=""
SCREENS=""
ICON=""
BRAND_COLOR=""
PALETTE=""
FRAME="none"
FRAME_COLOR=""
REPORT_FILE=""
while [[ $# -gt 0 ]]; do
case "$1" in
--bundle-id) BUNDLE_ID="$2"; shift 2 ;;
--template) TEMPLATE="$2"; shift 2 ;;
--app-name) APP_NAME="$2"; shift 2 ;;
--captures) CAPTURES_DIR="$2"; shift 2 ;;
--output) OUTPUT_DIR="$2"; shift 2 ;;
--copy) COPY_FILE="$2"; shift 2 ;;
--devices-sim) DEVICES_SIM="$2"; shift 2 ;;
--devices) DEVICES_GEN="$2"; shift 2 ;;
--locales) LOCALES="$2"; shift 2 ;;
--deeplinks) DEEPLINKS="$2"; shift 2 ;;
--screens) SCREENS="$2"; shift 2 ;;
--icon) ICON="$2"; shift 2 ;;
--brand-color) BRAND_COLOR="$2"; shift 2 ;;
--palette) PALETTE="$2"; shift 2 ;;
--frame) FRAME="$2"; shift 2 ;;
--frame-color) FRAME_COLOR="$2"; shift 2 ;;
--report) REPORT_FILE="$2"; shift 2 ;;
--help|-h)
cat <<HLP
Usage: shotkit screenshots [OPTIONS]
Runs the full pipeline: capture + generate + validate
Options:
--bundle-id ID App bundle ID (for capture)
--app-name NAME App display name (for generate)
--template STYLE Template: minimal, bold, dark, editorial, flat, trending
--captures DIR Raw captures directory (default: ./raw-captures)
--output DIR Output directory (default: ./screenshots-output)
--copy FILE Path to copy.json
--devices KEYS Generate device keys, e.g. 'iphone-6.9 ipad-13'
--devices-sim NAMES Simulator device names (comma-separated)
--locales CODES Locale codes, e.g. 'en-US it'
--deeplinks URLS Comma-separated deep link URLs
--screens NAMES Comma-separated screen names
--icon PATH App icon for auto-palette (trending)
--brand-color HEX Brand color e.g. '#1E90FF' (trending)
--palette NAME Trending palette name e.g. 'aurora'
--frame MODE Device frame: 'none' or 'device' (realistic bezel)
--frame-color COLOR Frame color: black-titanium, natural-titanium, etc.
--report FILE Write a JSON run report to FILE after validation
HLP
exit 0
;;
*) echo "Unknown option: $1"; exit 1 ;;
esac
done
# Try loading app name from .shotkit.json if not provided
if [ -z "$APP_NAME" ] && [ -f ".shotkit.json" ]; then
APP_NAME=$("$PYTHON" -c "import json; print(json.load(open('.shotkit.json')).get('app_name',''))" 2>/dev/null || true)
fi
if [ -z "$APP_NAME" ]; then
APP_NAME="MyApp"
echo " Warning: No --app-name provided, using '$APP_NAME'"
fi
# Step 1: Capture (if bundle ID provided)
if [ -n "$BUNDLE_ID" ]; then
echo "Step 1/3: Capturing screenshots..."
CAPTURE_ARGS=(--bundle-id "$BUNDLE_ID" --output "$CAPTURES_DIR" --devices "$DEVICES_SIM")
[ -n "$DEEPLINKS" ] && CAPTURE_ARGS+=(--deeplinks "$DEEPLINKS")
[ -n "$SCREENS" ] && CAPTURE_ARGS+=(--screens "$SCREENS")
bash "$SCRIPT_DIR/auto_capture.sh" "${CAPTURE_ARGS[@]}"
echo ""
else
echo "Step 1/3: Skipping capture (no --bundle-id, using existing captures in $CAPTURES_DIR)"
fi
# Step 2: Generate
echo "Step 2/3: Generating styled screenshots..."
read -ra DEVICES_GEN_ARR <<< "$DEVICES_GEN"
read -ra LOCALES_ARR <<< "$LOCALES"
GEN_ARGS=(--app-name "$APP_NAME" --captures "$CAPTURES_DIR" --template "$TEMPLATE" --devices "${DEVICES_GEN_ARR[@]}" --locales "${LOCALES_ARR[@]}" --output "$OUTPUT_DIR" --frame "$FRAME")
[ -n "$COPY_FILE" ] && GEN_ARGS+=(--copy "$COPY_FILE")
[ -n "$ICON" ] && GEN_ARGS+=(--icon "$ICON")
[ -n "$BRAND_COLOR" ] && GEN_ARGS+=(--brand-color "$BRAND_COLOR")
[ -n "$PALETTE" ] && GEN_ARGS+=(--palette "$PALETTE")
[ -n "$FRAME_COLOR" ] && GEN_ARGS+=(--frame-color "$FRAME_COLOR")
"$PYTHON" "$SCRIPT_DIR/generate_screenshots.py" "${GEN_ARGS[@]}"
echo ""
# Step 3: Validate
echo "Step 3/3: Validating output..."
VALIDATE_ARGS=(--dir "$OUTPUT_DIR")
[ -n "$REPORT_FILE" ] && VALIDATE_ARGS+=(--report "$REPORT_FILE")
"$PYTHON" "$SCRIPT_DIR/validate_output.py" "${VALIDATE_ARGS[@]}"
;;
palettes)
"$PYTHON" -c "
import sys; sys.path.insert(0, '$SCRIPT_DIR')
from trending import list_palettes
list_palettes()
"
;;
frame-colors)
"$PYTHON" -c "
import sys; sys.path.insert(0, '$SCRIPT_DIR')
from device_frames import list_frame_colors
list_frame_colors()
"
;;
install-deps)
exec bash "$SCRIPT_DIR/install_deps.sh" "$@"
;;
version|--version|-v)
echo "shotkit $VERSION"
;;
help|--help|-h)
usage
;;
*)
echo "Error: unknown command '$COMMAND'"
echo "Run 'shotkit --help' for usage."
exit 1
;;
esac