CLI Quickstart
Build your first brand-perfect slide in five steps. This tutorial walks you from an empty project to a finished, themed slide you can view in your browser.
Estimated time: 10--15 minutes.
You need the Pitch Smith CLI plugin installed before starting. If you have not installed it yet, follow the CLI Only install guide first, then come back here.
Step 1: Scaffold a Project
After this step, you'll have a new project directory with Pitch Smith's default structure, including a starter theme, templates, and a sample deck.
Open a terminal, create a folder for your presentation, and start a Claude Code session inside it:
mkdir my-presentation
cd my-presentation
claude
Inside the Claude Code session, run the smart router:
/pitchsmith
On first run, Pitch Smith detects that the workspace has not been set up yet. It automatically creates the .slide-builder/ directory, copies a default theme, starter templates, and a sample welcome deck into your project.
Verify: Project scaffolded successfully
After running /pitchsmith, check that the workspace directory was created:
ls .slide-builder/config/
Expected: You see files like theme.json and a catalog/ directory containing template definitions.
You should also see a sample deck in the output folder:
ls output/welcome-to-pitchsmith/slides/
Expected: HTML slide files such as slide-1.html, slide-2.html, slide-3.html.
If .slide-builder/ was not created, make sure you are running /pitchsmith inside a Claude Code session. See the Install guide for troubleshooting.
Pitch Smith uses a workspace to store everything about your presentations. The .slide-builder/ directory holds your theme (colors, fonts, shapes), templates (reusable slide layouts), and catalogs (indexes of available templates). Think of it as Pitch Smith's home base inside your project. The /pitchsmith command is the smart router -- it detects what state your workspace is in and guides you to the right next action.
Step 2: Set Up Your Brand
After this step, you'll have a brand theme with your company's colors, fonts, and visual style applied to all future slides.
Run the brand setup command:
/pitchsmith:setup
Pitch Smith asks you for brand source material. You can provide any combination of:
- A company website URL
- A brand guidelines PDF
- Logo files or screenshots
For this quickstart, providing just your website URL is enough. Pitch Smith analyzes the source material and generates a theme with your brand's color palette, typography, and visual personality.
If you do not have brand assets ready, you can skip this step. The default theme included during scaffolding works well for getting started. You can always run /pitchsmith:setup later.
Verify: Brand theme created
Check that your theme file was updated:
ls .slide-builder/config/theme.json
Expected: The file exists. If you provided brand assets, it now contains your custom colors and fonts. If you skipped brand setup, it contains the default theme.
You can also run /pitchsmith again -- the smart router will no longer suggest setting up a brand (it detected that your theme is ready) and will instead offer options to plan and build slides.
A theme is a JSON file that defines your visual identity: primary and accent colors, heading and body fonts, border radius, shadows, and more. Every slide Pitch Smith builds reads from this theme, so your entire deck stays visually consistent without manual styling. The /pitchsmith:setup command uses AI to extract these design decisions from your existing brand materials.
Step 3: Plan a Deck
After this step, you'll have a plan file describing the slides in your presentation, including titles, layouts, and key points for each slide.
Run the deck planning command:
/pitchsmith:plan-deck
Pitch Smith starts an interactive planning session. Describe the presentation you want to create. For example:
"A 3-slide intro deck for my team about our Q2 goals"
Pitch Smith asks follow-up questions to understand your content, audience, and goals, then generates a plan -- a YAML file that describes each slide's title, template, and key points.
Verify: Plan file created
After the planning session completes, check for your plan file:
ls output/
Expected: A new directory named after your deck (for example, output/q2-goals/) containing a plan.yaml file.
You can open the plan file to see the slide descriptions:
cat output/q2-goals/plan.yaml
Expected: A YAML file listing each slide with fields like title, template, and key_points.
A plan is Pitch Smith's blueprint for your presentation. Instead of building slides one at a time, you first describe the whole deck at a high level. The plan captures the narrative flow -- what each slide says, what layout it uses, and how slides connect. This separation of planning from building means you can revise the structure before committing to visual output.
Step 4: Build Your First Slide
After this step, you'll have an HTML slide built from your plan, styled with your brand theme, ready to view.
Run the build command:
/pitchsmith:build-one
Pitch Smith reads the first unbuilt slide from your plan, selects the matching template, applies your brand theme, and generates a fully styled HTML slide. The slide is saved to the output/ directory inside your deck folder.
Verify: Slide HTML file created
Check your deck's slides directory:
ls output/q2-goals/slides/
Expected: An HTML file such as slide-1.html.
You can also check the file size to confirm it has real content:
wc -c output/q2-goals/slides/slide-1.html
Expected: A file larger than 1 KB, indicating it contains a full HTML slide with styles and content.
The build step is where the magic happens. Pitch Smith combines three ingredients: your plan (what the slide says), your theme (how it looks), and a template (the structural layout). The result is a standalone HTML file -- a complete, self-contained slide with all styles inlined. No external CSS or JavaScript dependencies are needed to view it.
Step 5: View the Result
After this step, you'll see your finished slide rendered in the browser, styled with your brand.
Open the HTML file directly in any web browser:
open output/q2-goals/slides/slide-1.html
On Linux, use xdg-open instead of open. On Windows, use start.
Verify: Slide renders correctly
When you open the slide, you should see:
- A fully rendered slide with your content (title, key points, or other elements from the plan).
- Your brand colors applied to headings, backgrounds, and accents.
- Your brand fonts used for headings and body text.
- A clean, professional layout based on the template.
If the slide appears unstyled or blank, check that the HTML file is not empty (wc -c should show more than 1 KB). If the build step did not complete, re-run /pitchsmith:build-one.
Each slide is a standalone HTML file. You can open it in any browser, share it by email, or embed it in other tools. The Pitch Smith Slide Viewer (available in the VS Code extension) adds presentation features like slide navigation, fullscreen mode, and build animations -- but the HTML file works perfectly on its own.
Congratulations!
You just went from an empty directory to a branded, professional slide in five steps. Here is what you accomplished:
- Scaffolded a Pitch Smith workspace with templates and a default theme.
- Set up your brand so every slide matches your visual identity.
- Planned a deck using natural language to describe your presentation.
- Built a slide that combines your plan, theme, and a template into HTML.
- Viewed the result in your browser.
Ready to build all the remaining slides? Run:
/pitchsmith:build-all
This builds every unbuilt slide in your plan in one batch. You can view the full deck in the Slide Viewer or open each HTML file individually.
Next Steps
Now that you have built your first slide, explore these guides to go deeper:
- VS Code Quickstart -- See the visual UI workflow with the Slide Viewer, Catalog panel, and more.
- Brand Setup -- Learn how to refine your theme, provide feedback on extracted colors, and use the visual Theme Editor.
- Core Concepts -- Understand how themes, templates, plans, and the build pipeline work together.