CLI reference

The SuperDeck CLI provides tools for setting up, building, and publishing presentations. This reference covers all commands and options.

Installation

dart pub global activate superdeck_cli

Global options

These options work with all commands:

Commands

superdeck setup

Initialize SuperDeck in a Flutter project. Creates a sample slides.md file, updates pubspec.yaml with asset configuration, sets up macOS entitlements for network access, and configures a custom index.html for web.

superdeck setup

Options:

superdeck build

Build presentations from markdown files. Parses slides.md, generates presentation data in .superdeck/superdeck.json, and creates optimized assets.

superdeck build [options]

Options:

Examples:

# Build once
superdeck build

# Build and watch for changes (recommended for development)
superdeck build -w

# Force rebuild everything
superdeck build -f

superdeck publish

Publish presentation to GitHub Pages. Builds the web version with proper base-href, commits to the target branch using git worktree, and optionally pushes to remote.

superdeck publish [options]

Options:

Examples:

# Publish to gh-pages branch
superdeck publish

# Publish with custom message
superdeck publish -m "Update presentation"

# Skip build step (if already built)
superdeck publish --no-build

# Preview without making changes
superdeck publish --dry-run

superdeck version

Print the SuperDeck CLI version.

superdeck version

File structure

After running CLI commands, your project will have:

project/
├── slides.md                    # Your presentation content
├── pubspec.yaml                 # Updated with asset configuration
├── .superdeck/
│   ├── superdeck.json          # Generated presentation data
│   ├── superdeck_full.json     # Includes markdown AST JSON (for debugging)
│   ├── generated_assets.json   # Asset manifest
│   ├── build_status.json       # Last build status
│   └── assets/                 # Generated assets (for example, Mermaid PNGs)
│       ├── mermaid_<hash>.png
│       └── thumbnail_<slideKey>.png  # Generated at runtime
└── web/
    └── index.html              # Custom index with loading indicator

Configuration

pubspec.yaml updates

The CLI automatically adds this to your pubspec.yaml:

flutter:
  assets:
    - .superdeck/
    - .superdeck/assets/

macOS entitlements

For macOS projects, superdeck setup updates macos/Runner/Release.entitlements and macos/Runner/DebugProfile.entitlements to allow network access (required for remote images and DartPad):

<key>com.apple.security.app-sandbox</key>
<false/>
<key>com.apple.security.network.client</key>
<true/>

In debug builds, it also enables com.apple.security.network.server and com.apple.security.cs.allow-jit.

Common workflows

Development workflow

# Terminal 1: Start CLI in watch mode
superdeck build --watch

# Terminal 2: Run Flutter app
flutter run

Publishing workflow

# Build and test locally
superdeck build
flutter run -d web

# Publish to GitHub Pages
superdeck publish

Troubleshooting workflow

# Verbose output for debugging
superdeck build --verbose

# Force rebuild if assets are corrupted  
superdeck build --force-rebuild

# Check what publish would do
superdeck publish --dry-run

Exit codes

Common issues

Build fails

Problem: Error: slides.md not found Solution: Ensure slides.md exists in project root or run superdeck setup

Problem: Error: Invalid markdown syntax
Solution: Check your markdown syntax, especially block definitions and frontmatter

Publish fails

Problem: Error: Not a git repository Solution: Initialize git repository: git init && git add . && git commit -m "Initial commit"

Problem: Error: No changes to commit Solution: This is informational. Make a change (or run superdeck build --force-rebuild) and publish again.

Watch mode issues

Problem: Changes not detected Solution: Ensure you're editing slides.md in the project root

Problem: Build errors in watch mode Solution: Fix the error and save again; watch mode will retry automatically

Performance tips

1. Use watch mode - superdeck build --watch is optimized for development
2. Cache remote images - Remote images are cached at runtime by cached_network_image
3. Skip pubspec updates - Use --skip-pubspec if you manage assets manually
4. Incremental builds - Only changed assets are rebuilt by default

Integration with CI/CD

GitHub Actions example

name: Deploy SuperDeck
on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: subosito/flutter-action@v2
    - run: dart pub global activate superdeck_cli
    - run: superdeck build
    - run: superdeck publish