agentpreso login

Prompts for email and password, then saves an API key locally. Verify with agentpreso whoami.

Reading Strategy (for AI agents)

Read this file first. Only read additional docs when needed:

Building a custom theme? → docs/DESIGN-GUIDE.md, then the Custom Themes section below
Adding charts/diagrams? → the Charts and Diagrams section below
Logo handling? → the Logos section below

Don't front-load all references — read them just-in-time.

CLI Quick Reference

# Auth
agentpreso login                          # Authenticate
agentpreso whoami                         # Check current user

# Themes
agentpreso themes                         # List available themes
agentpreso themes show <name>             # Show theme details
agentpreso themes add <path>              # Upload custom theme directory
agentpreso themes update <name> theme.yaml  # Update theme from manifest
agentpreso themes update <name> --css f.css # Update raw CSS only
agentpreso themes delete <name>           # Delete custom theme

# Decks — local-first workflow
agentpreso new <file> -t <theme>          # Scaffold local markdown file
agentpreso push [file]                    # Push local file to cloud (creates or updates)
agentpreso pull <slug>                    # Download cloud deck to local file
agentpreso list                           # List cloud decks

# Rendering
agentpreso render <file> --format pdf     # Export to html, pdf, or pptx
agentpreso render <file> --var company="Acme" --vars data.yaml
agentpreso preview <file> -s 1            # Preview slide as PNG (for verification)
agentpreso serve <file>                   # Live preview server with hot reload

# Content generation
agentpreso add-graphic <slug> "prompt"    # AI-generate image into deck
agentpreso add-illustration <slug> --file drawing.yaml
agentpreso render-chart chart.yaml        # Render chart YAML to SVG
agentpreso render-diagram flow.mmd        # Render Mermaid to SVG

# Assets
agentpreso assets upload <file>           # Upload image for use in slides
agentpreso assets                         # List uploaded assets

# Sharing
agentpreso share <slug>                   # Generate public share link
agentpreso share <slug> --private         # Revoke public access

Workflow

AgentPreso uses a local-first workflow: edit markdown files locally, push to cloud for rendering.

Start: agentpreso themes — pick a theme that matches the tone
Create: Write a .md file (see format below), or agentpreso new deck.md -t corporate
Push: agentpreso push deck.md — uploads to cloud, prints a dashboard link (requires login)
Preview: agentpreso preview deck.md -s 1 — check each slide as PNG
Iterate: Edit the local file, re-push, re-preview until satisfied
Deliver: Always give the user the dashboard URL from push so they can view their slides
Export: agentpreso render deck.md --format pdf — check response for warnings
Share (optional, requires consent): Only if the user explicitly asks for a public link, run agentpreso share deck-slug. You MUST ask the user for confirmation before sharing — this creates a public URL accessible to anyone without authentication.

For cloud-only editing (no local file), use agentpreso pull <slug> to fetch, edit, then agentpreso push.

Previewing Slides

Use agentpreso preview <file> -s <n> to render a single slide as PNG. To review multiple slides, run preview for each slide index sequentially. Always preview after push to verify charts, diagrams, and images rendered correctly. If the preview shows a red error block, the chart/diagram has a syntax error — fix before continuing.

Sharing

WARNING: agentpreso share creates a PUBLIC link accessible to anyone without authentication. Never run this command without explicit user consent. The presentation may contain confidential information.

To generate a share link (only after the user confirms they want a public link):

agentpreso share <deck-slug>

To revoke public access:

agentpreso share <deck-slug> --private

Render Warnings

After rendering, check the response for warnings. If any chart, diagram, or image errors occurred, they appear in the warnings array. Fix all warnings before sharing — they indicate broken content in the rendered output.

Markdown Format

Standard markdown. Slides separated by ---. Deck-level frontmatter sets theme and options. Per-slide frontmatter sets layout and directives:

---
theme: corporate
paginate: true
---

# Title Slide

---
layout: bullets
---

## Content Slide

- Bullet points work naturally

---
layout: quote
---

> "Styled blockquote"
>
> — Attribution

Per-Slide Frontmatter

Each slide can have its own YAML frontmatter block (Slidev-style). The layout key maps to the slide's CSS class:

---
layout: bullets
---

## My Bullets
- Point A
- Point B

Supported per-slide keys: layout, class, transition, backgroundColor, backgroundImage, fragments, fragmentType, paginate, header, footer, color, style.

The layout key is the primary way to set a slide's layout. Alternative:  (HTML comment syntax, still supported).

Named Slots

For multi-column and container layouts, use ::name:: syntax to route content into named slots:

---
layout: two-col
---

## Comparison

::left::
### Option A
- First benefit

::right::
### Option B
- Different benefit

Available slot names: left, right, center, col, column, stat. The :::name ... ::: container syntax is also supported as an alternative.

Pagination directives

Directive	Effect
`<!-- _paginate: false -->`	Hide page number
`<!-- _paginate: skip -->`	Hide and don't count (use on title)
`<!-- _paginate: hold -->`	Same number as previous slide

These can also be set via per-slide frontmatter: paginate: false, paginate: skip, paginate: hold.

Slide Layouts

Apply with per-slide frontmatter layout: layout-name (preferred) or :

Opening & Closing

Layout	Use For
`title-hero`	Opening title slide
`chapter`	Section dividers
`full-bleed-title`	Title over full-bleed background image
`title-img`	Title slide with side image
`quote-hero`	Bold quote as opening/closing statement
`summary`	Key takeaways with checkmarks
`cta`	Call-to-action closing slide

Content

Layout	Use For
`bullets`	Standard bullet lists
`steps`	Numbered sequences
`focus`	Single key message, centered
`definition`	Term/definition pairs
`agenda`	Meeting or talk agenda
`cards`	Card grid for features or concepts
`custom`	Blank canvas for agent-authored HTML with component classes

Media

Layout	Use For
`img-right` / `img-left`	Text + image split
`img-center`	Centered image with caption
`img-top`	Image above text content
`full-bleed`	Full-screen background image
`gallery`	Multi-image grid
`figure`	Wide visual (diagram/chart/image) with brief text

Data

Layout	Use For
`stats-grid`	2x2 metric display
`stats-row`	Horizontal row of metrics
`big-number`	Single hero statistic
`timeline`	Horizontal sequence of events

Comparison

Layout	Use For
`two-col`	Side-by-side content
`two-col-wide-right`	Two columns, right side wider
`three-col`	Three equal columns
`before-after`	Before/after comparison
`pros-cons`	Pros and cons with icons
`matrix`	2x2 grid of categories

Dark Mode Per-Slide

Add invert to flip any slide to dark palette. Combine with layouts:

---
layout: invert title-hero
---

# Dark Opening Slide

Alternative syntax: 

Charts, diagrams, and images auto-adapt to dark background.

Images

Upload first, then reference by asset URI:

![Description](asset://asset_abc123)

Logos

Use an existing logo file (SVG or PNG). Download it first if needed:

curl -o logo.png "https://example.com/logo.png"
agentpreso assets upload logo.png

Then reference via asset URI in slides, or attach to a theme:

agentpreso themes add ./my-theme/ --logo logo.svg

Do NOT attempt to reconstruct logos from HTML/CSS/JS extraction — use intact image files.

Charts and Diagrams

```chart
type: bar
data:
  labels: [Q1, Q2, Q3, Q4]
  datasets:
    - label: Revenue
      data: [10, 15, 12, 18]
```

```mermaid
graph LR
    A[Start] --> B[Process] --> C[End]
```

Template Variables

Define defaults in frontmatter, override at render time:

---
agentpreso:
  theme: corporate
  vars:
    company: "Acme Corp"
    deal_size: "$500K"
---

# Proposal for {{company}}
Deal size: {{deal_size}}

Override: agentpreso render deck.md --var company="Contoso" --var deal_size="$1.2M"

Or from a file: agentpreso render deck.md --vars overrides.yaml

Slide Design Principles

Every slide needs visual structure — use layouts, bold hierarchy, tables, callouts, and stats. Charts and images are powerful but not required on every slide.
One topic per slide — but density is OK. A table + callouts + stats serving one topic is better than 3 sparse slides.
Match density to purpose — board decks and data analysis should be information-dense. Keynotes and narratives should breathe. There's no single right density.
Create visual rhythm — vary layouts, alternate dense and simple slides, mix data with narrative. Don't repeat the same layout three times in a row.
Bold text is your main tool — **bold** renders in heading color in bullets, tables, and stats. Use it to create visual anchors that guide the eye.
Preview before done — always check with agentpreso preview before declaring finished.

Writing Beautiful Markdown

The CSS does heavy lifting — but only if you write markdown that gives it something to work with. These patterns produce noticeably better slides:

Bullet lists with bold titles: Lead each item with a bold phrase. The CSS renders the bold text in heading color, creating visual anchors:

- **Revenue grew 42%** — driven by enterprise expansion and seat upgrades
- **Net retention hit 130%** — expansion outpacing churn 6:1
- **Gross margin at 94%** — infrastructure migration cut per-query cost 44%

Nested bullets as descriptions: Sub-items render smaller in secondary color — like a title + description pattern:

- **Revenue grew 42%**
  - Driven by enterprise expansion and seat upgrades across all segments
- **Net retention hit 130%**
  - Expansion outpacing churn 6:1, with enterprise NRR at 145%

Tables with bold emphasis: Bold cells get heading color automatically. Use bold for the numbers you want to stand out:

| Metric     | Q3      | Q4        | Change       |
|------------|---------|-----------|--------------|
| ARR        | $6.8M   | **$10.2M**| **+50%**     |
| Customers  | 380     | **528**   | **+39%**     |

Blockquote callouts: Use blockquotes for contextual annotations. Lead with a bold title line:

> **Revenue on track**
> Q4 exceeded forecast by 12%, driven by enterprise expansion.

Stats with bold values: In stats-grid and stats-row layouts, bold text becomes the hero number:

Revenue
**$10.2M**

Data-Dense Slides

For board decks, financial reports, and analytical presentations, single-topic slides with multiple components create the most professional output. Use two-col or three-col layouts to combine:

A table in one column showing the data
Callouts in the other column providing context and interpretation
Stat boxes summarizing key numbers

Example structure:

---
layout: two-col
---
## Revenue by Segment

::left::
| Segment | ARR | Growth |
|---------|-----|--------|
| Enterprise | **$5.8M** | **+68%** |
| Mid-Market | $2.9M | +41% |
| SMB | $1.5M | +12% |

::right::
> **Enterprise is the growth engine**
> Average ACV doubled from $119K to $200K.

> **SMB churn needs attention**
> 4.2% quarterly — 16% annualized.

This produces a slide with a clean data table on the left and interpretive callouts on the right — far more useful than splitting this across 3 slides.

Custom HTML Slides

For layouts not covered by built-in options, use layout: custom with raw HTML. The slide inherits theme variables but imposes no structural CSS.

Prefer component classes over inline styles. The base CSS includes pre-styled components that work across all themes:

Class	What it renders
`.callout` + `.callout-success` / `-warning` / `-danger` / `-info` / `-primary`	Colored annotation box with title + body
`.stat-box` + `.stat-box-success` / `-warning` / `-danger` / `-info` / `-primary`	Bordered metric box with value + label
`.stat-box-value`, `.stat-box-label`, `.stat-box-detail`	Stat box inner elements
`.card` + `.card-title`	Container that can wrap tables, stats, callouts
`.bar-row` + `.bar-label` / `.bar-track` / `.bar-fill` / `.bar-value`	CSS-only horizontal bar chart
`.bar-fill-success` / `-warning` / `-danger` / `-info`	Bar fill color variants
`.summary-grid` + `.summary-item` / `.summary-total`	Row of big numbers with optional total
`.summary-item-value`, `.summary-item-label`	Summary grid inner elements
`.quadrant-grid` + `.quadrant` + `.quadrant-title`	2x2 colored matrix
`.quadrant-success` / `-warning` / `-danger` / `-info`	Quadrant background variants
`.action-badge` + `.action-num` / `.action-text` / `.action-impact`	Numbered action items

Authoring priority:

Standard markdown with a named layout (best — simplest, most portable)
layout: custom with component classes (good — structured, theme-aware)
layout: custom with inline styles and theme variables (acceptable — one-off designs)
<style> or <script> blocks (forbidden — stripped at render time)

Semantic colors available in all components and via inline styles: var(--color-success), var(--color-warning), var(--color-danger), var(--color-info) — plus -light variants for backgrounds.

Example custom slide with components:

---
layout: custom
---

<div style="display: grid; grid-template-columns: 3fr 2fr; gap: 2rem; height: 100%;">
  <div class="card">
    <div class="card-title">Revenue by Segment</div>
    <!-- markdown table or HTML table here -->
  </div>
  <div>
    <div class="callout callout-success">
      <h5>Enterprise is the engine</h5>
      <p>ACV doubled to $200K. Net retention at 145%.</p>
    </div>
    <div class="callout callout-warning" style="margin-top: 1rem;">
      <h5>SMB churn rising</h5>
      <p>4.2% quarterly churn — needs the Growth tier.</p>
    </div>
  </div>
</div>

Diagrams and Charts — Layout Rules

Be cautious mixing long lists with large visuals. If a chart or diagram shares a slide with bullets, keep the list short (3-4 items max) and use two-col or figure layout to give each element room. The renderer will warn if content overflows.

Visual scenario	Layout to use	Why
Wide diagram + brief context	`figure`	Full-width visual with heading + 1-2 line description
Diagram alongside bullets	`two-col`	Visual in one column, bullets in the other
Full-width chart, minimal text	`figure` or no class	Heading + chart block fills the slide
Chart with detailed breakdown	`two-col`	Chart in one column, bullet legend in the other

For detailed theme design guidance (color palettes, typography, CSS variables, logo placement), see docs/DESIGN-GUIDE.md.

Built-in Themes

Theme	Style	Best For
`agentpreso`	Modern	Navy warmth, tangerine accents — the default brand theme
`ink`	Editorial	Serif typography, newspaper red — reports, longform
`neon`	Cyberpunk	Cyan glow on near-black — product launches, tech keynotes
`terminal`	Retro	Green phosphor CRT — developer content, CLIs
`chalk`	Educational	Handwriting headings, teal — workshops, tutorials
`blueprint`	Technical	Grid overlay, engineering precision — architecture, specs
`ember`	Cinematic	Warm amber on dark — storytelling, brand narratives
`glacier`	Analytical	Cool blues, data-focused — dashboards, analytics
`botanica`	Organic	Forest green, gold serif — sustainability, luxury
`maison`	Luxury	Matte gold, minimalist — high-end proposals, fashion

Custom Themes

Create a directory with theme.yaml (required), optional overrides.css and scaffold.md, then:

Font limitation: Only web-safe and Google Fonts render correctly. Proprietary fonts (e.g., CiscoSans, BrandFont) will fall back to system fonts. Use close alternatives: Inter, DM Sans, Source Sans Pro, etc.

Theme Customization Strategy

Use theme.yaml manifest options (colors, fonts, imagery) for all standard customization. Do NOT create overrides.css unless the user explicitly requests styling that cannot be achieved through theme.yaml parameters. The manifest covers colors, fonts, spacing, imagery guidance, and layout preferences — overrides.css is a last-resort escape hatch, not a default tool.

Usage:

agentpreso themes add ./my-theme/
agentpreso themes add ./my-theme/ --logo logo.svg --logo-position bottom-right --logo-size small

To update an existing theme, point to the theme.yaml file directly:

agentpreso themes update my-brand ./my-theme/theme.yaml

This re-assembles CSS from the manifest, auto-discovers overrides.css and logo files from the same directory, and updates the theme in-place (preserving logo asset IDs when logos haven't changed).

agentpreso

AgentPreso

Getting Started

1. Install the CLI

2. Create an account

3. Authenticate