CLI reference

The SuperDeck CLI provides tools for configuring and building 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

Configure the current Flutter app for SuperDeck. This creates .superdeck/ directories, patches pubspec.yaml assets, and patches macOS entitlements when macos/ exists.

cd my_presentation
superdeck setup

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

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)
    └── build_status.json       # Last build status

Runtime slide thumbnails are referenced by key (thumbnail_<slideKey>.png) and cached by the app at runtime (OS application cache on native platforms, in-memory data URIs on web).

Configuration

pubspec.yaml updates

The CLI automatically adds this to your pubspec.yaml:

flutter:
  assets:
    - .superdeck/

Common workflows

Development workflow

# Terminal 1: Start CLI in watch mode
dart run superdeck_cli:main build --watch

# Terminal 2: Run Flutter app
flutter run

Troubleshooting workflow

# Verbose output for debugging
dart run superdeck_cli:main build --verbose

Exit codes

Common issues

Build fails

Problem: Error: slides.md not found Solution: Ensure slides.md exists in the project root. Run superdeck setup if the app still needs SuperDeck asset entries or macOS entitlements.

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

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

Deploying to GitHub Pages

SuperDeck builds a plain Flutter web app, so any Flutter web deployment pipeline works. Two pieces are easy to forget and cause the most common failures:

• Pass --base-href "/<repo>/" to flutter build web so asset URLs resolve under the Pages subpath.
• Write an empty .nojekyll file at the root of the published output so Pages does not drop Flutter's _flutter/ directory.

GitHub Actions example

name: Deploy to GitHub Pages
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
        with:
          channel: stable
      - run: dart pub global activate superdeck_cli
      - run: superdeck build
      - run: flutter build web --release --base-href "/${{ github.event.repository.name }}/"
      - run: touch build/web/.nojekyll
      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build/web

Performance tips

1. Use watch mode - dart run superdeck_cli:main 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