cli

Slide Spec CLI

Create beautiful slides from YAML - presentations as structured data for open sharing and collaboration. Built for open source, usable everywhere.

Write presentations as structured data. Version control them like code, review them in pull requests, and publish static sites without relying on proprietary slide formats.

Why Slide Spec?

Slide Spec is for technical maintainers, docs-as-code teams, and open source projects that want presentations to be:

• Structured instead of hand-edited in opaque binaries
• Version controlled alongside code and docs
• Reviewable in pull requests
• Reusable across updates, releases, briefings, and reports
• Openly shareable as static web output without proprietary authoring tools

⚡ Quickstart

Get a working deck in under two minutes.

npx @slide-spec/cli init my-slides
cd my-slides
npx @slide-spec/cli serve

From there, edit your content, validate it, fetch generated GitHub-backed content if needed, and build:

npx @slide-spec/cli validate
# Requires GITHUB_PAT, GITHUB_TOKEN, or GH_TOKEN in your environment or in a .env file at the project root
npx @slide-spec/cli fetch
npx @slide-spec/cli build

✨ Install

Run without installing:

npx @slide-spec/cli <command>

Or install globally:

npm install -g @slide-spec/cli

Then run:

slide-spec help

🧰 Commands

[root] is an optional path to the Slide Spec project directory. If omitted, the CLI uses your current working directory.

Command	Description
slide-spec help	List commands
slide-spec init [root]	Scaffold a project interactively
slide-spec validate [root]	Validate Slide Spec YAML in the target project directory
slide-spec fetch [root]	Fetch GitHub data into generated content for the target project directory
slide-spec build [root]	Build a static site to <root>/dist
slide-spec serve [root]	Build and serve the target project locally

Example:

slide-spec serve ./my-slides

Per-command help:

slide-spec <command> --help

🔐 GitHub Integration

fetch can enrich generated content with GitHub data.

To enable authenticated GitHub-backed fetches, set a token in your shell environment or copy .env.example to .env in your project root and set:

GITHUB_PAT=your_token_here

Notes:

• A token is optional
• GITHUB_PAT, GITHUB_TOKEN, and GH_TOKEN are supported; shell environment values take precedence over .env
• fetch supports best-effort mode without a token
• init can write a masked GITHUB_PAT entry into .env during setup
• fetch also supports date ranges

🛠️ Development

From the monorepo:

pnpm install
pnpm --filter @slide-spec/cli cli -- help

Development and quality commands:

Command	Description
pnpm --filter @slide-spec/cli build	Compile the CLI
pnpm --filter @slide-spec/cli verify	Lint + typecheck + tests
pnpm --filter @slide-spec/cli coverage	Unit tests with coverage
pnpm --filter @slide-spec/cli semgrep	Semgrep security scan
pnpm --filter @slide-spec/cli spellcheck	Spelling check

Requirements

• Node.js 24+
• pnpm
• Docker for pnpm verify:ci

Quality Gates

pnpm --filter @slide-spec/cli verify is the package gate.

CI also runs:

• semgrep
• spellcheck

📝 Notes

• Uses ../shared for content types and validation
• Running with no args enters interactive mode
• Accepts an explicit project root, so it also works against external Slide Spec projects
• build --deployment-url <url> enables sitemap.xml generation

🚢 Releases

The CLI is published to npm as @slide-spec/cli.

⚠️ Pre-1.0 — minor versions may contain breaking changes without prior deprecation. Pin your version if you need stability.

Tagged releases publish through CI.

• Stable releases publish to latest
• Prereleases publish to alpha, beta, or rc based on the tag suffix