CLI Reference

The AgentPreso CLI is a standalone binary that works with local files and cloud storage. No Node.js required.

Global Options

These options apply to all commands:

Option	Description
`--help`, `-h`	Show help for a command
`--version`, `-v`	Show CLI version
`--config <path>`	Use a custom config file
`--quiet`, `-q`	Suppress non-error output
`--verbose`	Show detailed output

Authentication Commands

`agentpreso login`

Authenticate with the AgentPreso server and store your API key locally.

agentpreso login

Opens a browser window for authentication. After successful login, your API key is stored in ~/.agentpreso/credentials.

Options:

Option	Description
`--server <url>`	Use a custom server URL
`--key <api-key>`	Provide an API key directly (non-interactive)

`agentpreso logout`

Remove stored credentials.

agentpreso logout

`agentpreso whoami`

Display the currently authenticated user and server.

agentpreso whoami

Output:

Logged in as: [email protected]
Server: https://api.agentpreso.com

Deck Commands

`agentpreso create <name>`

Create a new presentation from a theme.

agentpreso create quarterly-review

Options:

Option	Description
`--theme`, `-t`	Theme to use (default: `minimal`)
`--output`, `-o`	Output directory (default: current directory)

Examples:

# Create with corporate theme
agentpreso create sales-deck --theme corporate

# Create in a specific directory
agentpreso create pitch --output ./presentations

`agentpreso render <file>`

Render a presentation to HTML, PDF, or editable PowerPoint.

agentpreso render presentation.md

Options:

Option	Description
`--format`, `-f`	Output format: `html`, `pdf`, `pptx` (default: `html`)
`--output`, `-o`	Output file path
`--theme`, `-t`	Override theme from frontmatter
`--watch`, `-w`	Watch for changes and re-render
`--vars <file>`	Load template variables from a YAML or JSON file
`--var <key=value>`	Set a template variable (repeatable, overrides `--vars` file)

Examples:

# Render to PDF
agentpreso render deck.md --format pdf

# Render to editable PowerPoint
agentpreso render deck.md --format pptx

# Custom output path
agentpreso render deck.md --format pdf --output ./output/final.pdf

# Watch mode
agentpreso render deck.md --watch

# Render with template variables from a file
agentpreso render proposal.md --vars client-data.yaml

# Render with inline variable overrides
agentpreso render proposal.md --var company="Contoso" --var deal_size="\$1.2M"

# Combine file + inline overrides (inline wins)
agentpreso render proposal.md --vars defaults.yaml --var company="Override"

PPTX Export Notes:

PPTX exports produce editable slides — text, bullets, and tables can be modified directly in PowerPoint
Diagrams (Mermaid) and charts are embedded as high-quality PNG images
Theme colors and fonts are applied to the PPTX theme
Powered by Pandoc for reliable conversion

`agentpreso serve <file>`

Start a local development server with hot-reload preview.

agentpreso serve presentation.md

Options:

Option	Description
`--port`, `-p`	Server port (default: `3000`)
`--host`	Host to bind to (default: `localhost`)
`--open`	Open browser automatically

Examples:

# Custom port
agentpreso serve deck.md --port 8080

# Open browser automatically
agentpreso serve deck.md --open

`agentpreso push [file]`

Upload a local deck to cloud storage.

agentpreso push presentation.md

If no file is specified, pushes all .md files in the current directory that have AgentPreso frontmatter.

Options:

Option	Description
`--name <name>`	Override the deck name/slug

Examples:

# Push with custom name
agentpreso push deck.md --name q3-results

`agentpreso pull <slug>`

Download a cloud deck to a local file.

agentpreso pull quarterly-review

Options:

Option	Description
`--output`, `-o`	Output file path (default: `<slug>.md`)
`--force`	Overwrite existing local file

Examples:

# Custom output path
agentpreso pull q3-results --output ./decks/q3.md

`agentpreso list`

List your cloud decks.

agentpreso list

Options:

Option	Description
`--json`	Output as JSON
`--limit`, `-n`	Maximum number of results

Output:

SLUG              TITLE                    UPDATED
quarterly-review  Q3 2024 Review           2 hours ago
sales-pitch       Enterprise Sales Deck    3 days ago
onboarding        New Hire Onboarding      1 week ago

`agentpreso decks list`

List all decks with format options. Alias for agentpreso list with additional output formats.

agentpreso decks list

Options:

Option	Description
`--format <format>`	Output format: `table` or `json` (default: `table`)

`agentpreso decks show <id>`

Show full details of a deck including ID, slug, title, theme, timestamps, and complete markdown content.

agentpreso decks show deck_abc123

`agentpreso decks delete <id>`

Delete a deck permanently.

agentpreso decks delete deck_abc123

`agentpreso share <file-or-id>`

Generate or manage a public sharing link for a deck. Accepts a local file path (looks up deck ID from .agentpreso.json) or a deck ID directly.

agentpreso share presentation.md

Options:

Option	Description
`--public`	Enable public sharing (default behavior)
`--private`	Disable public sharing
`--revoke`	Revoke public access (alias for `--private`)

Examples:

# Enable sharing for a local file
agentpreso share deck.md

# Enable sharing by deck ID
agentpreso share abc123

# Disable public sharing
agentpreso share deck.md --private

# Revoke public access
agentpreso share deck.md --revoke

`agentpreso preview <file>`

Preview a specific slide as a PNG image. Useful for AI agent verification of slide output.

agentpreso preview presentation.md --slide 1

Options:

Option	Description
`--slide`, `-s`	Required. Slide number to preview (1-indexed)
`--output`, `-o`	Custom output file path (default: `<name>-slide<N>.png`)
`--theme <id>`	Theme ID to use

Examples:

# Preview slide 3
agentpreso preview deck.md --slide 3

# Save to a custom path
agentpreso preview deck.md --slide 1 --output ./previews/title.png

# Preview with a specific theme
agentpreso preview deck.md --slide 2 --theme corporate

Theme Commands

`agentpreso themes`

List available themes.

agentpreso themes

Options:

Option	Description
`--json`	Output as JSON

Output:

NAME        DESCRIPTION                              TYPE
minimal     Clean, lots of whitespace                built-in
dark        Dark background, high contrast           built-in
corporate   Professional, muted blues/grays          built-in
creative    Bold colors, modern typography           built-in
agentpreso  Navy and tangerine brand theme           built-in
my-brand    Custom company branding                  custom

`agentpreso themes add <path>`

Upload a custom theme to your account.

agentpreso themes add ./my-theme/

The path should be a directory containing:

theme.yaml - manifest file
overrides.css - optional CSS overrides
scaffold.md - optional starter content
assets/ - optional directory with images

Logo Options:

Option	Description
`--logo <file>`	Path to primary logo file
`--logo-light <file>`	Path to light variant logo (for dark backgrounds)
`--logo-position <pos>`	Logo position: `top-left`, `top-center`, `top-right`, `left-center`, `center`, `right-center`, `bottom-left`, `bottom-center`, `bottom-right`, `none`
`--logo-size <size>`	Logo size: `small`, `medium`, `large`, or `WIDTHxHEIGHT` (e.g., `80x60`)
`--logo-pages <pages>`	Which pages to show logo: `all`, `first`, `last`, `first-and-last`, `content`
`--logo-placement <file>`	Path to JSON file with advanced placement rules
`--logo-placement-json <json>`	Inline JSON with advanced placement rules

Examples:

# Upload theme with logo
agentpreso themes add ./my-theme --logo ./assets/logo.png

# Upload with logo position and size
agentpreso themes add ./my-theme \
  --logo ./assets/logo.svg \
  --logo-position bottom-right \
  --logo-size small

# Upload with light variant for dark backgrounds
agentpreso themes add ./my-theme \
  --logo ./assets/logo-dark.png \
  --logo-light ./assets/logo-light.png

# Upload with advanced placement rules
agentpreso themes add ./my-theme \
  --logo ./assets/logo.png \
  --logo-placement-json '{"default":{"position":"bottom-right","size":"small"},"lead":{"position":"top-left","size":"large"}}'

`agentpreso themes update <name> [theme-file]`

Update a custom theme. Pass a theme.yaml file to update the full manifest (colors, fonts, style), or use flags for targeted updates.

# Update from theme.yaml — re-assembles CSS, auto-discovers overrides.css and logos
agentpreso themes update my-brand ./my-theme/theme.yaml

# Update just the CSS overrides
agentpreso themes update my-brand --css ./overrides.css

# Update logo
agentpreso themes update my-brand --logo ./new-logo.png

When a theme.yaml file is provided, the command:

Reads the manifest and sends it to the server for CSS assembly
Auto-discovers overrides.css in the same directory (appended to assembled CSS)
Auto-discovers and uploads logo files (logo.svg, logo-alt.svg, etc.) from the same directory
Derives logo placement from the manifest’s logo section

Logo Options: Same as themes add above.

Examples:

# Update logo position only
agentpreso themes update my-brand --logo-position top-left

# Update with new logo file and size
agentpreso themes update my-brand \
  --logo ./updated-logo.svg \
  --logo-size medium

`agentpreso themes show <name>`

Show theme details including logo configuration.

agentpreso themes show my-brand

`agentpreso themes rename <old-name> <new-name>`

Rename a custom theme.

agentpreso themes rename my-brand my-company-brand

`agentpreso themes delete <name>`

Delete a custom theme.

agentpreso themes delete my-brand

Content Generation Commands

`agentpreso add-graphic <slug> <prompt>`

Generate an AI graphic and add it to a cloud deck. Uses Google Imagen to create images from text prompts.

agentpreso add-graphic my-deck "A futuristic cityscape at sunset"

Options:

Option	Description
`--slide <index>`	Zero-based slide index (creates new slide if omitted)
`--position <pos>`	Image placement: `background`, `inline`, `left`, `right` (default: `inline`)
`--title <text>`	Title for new slide (only when creating a new slide)
`--aspect <ratio>`	Aspect ratio: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`
`--style <style>`	Style: `photo`, `illustration`, `icon`, `abstract`, `minimal`
`--alt <text>`	Alt text for accessibility

Examples:

# Add background image to slide 0
agentpreso add-graphic my-deck "Mountain landscape" --slide 0 --position background

# Add illustration with custom aspect ratio
agentpreso add-graphic my-deck "Team collaboration" --aspect 16:9 --style illustration

`agentpreso add-illustration <slug>`

Add an Excalidraw-style hand-drawn illustration to a cloud deck using a YAML DSL.

agentpreso add-illustration my-deck --file drawing.yaml

Options:

Option	Description
`--yaml <yaml>`	Inline YAML DSL content
`--file <path>`	Path to YAML DSL file
`--slide <index>`	Zero-based slide index
`--title <title>`	Title for new slide

`agentpreso render-diagram <file>`

Render a Mermaid diagram file to SVG.

agentpreso render-diagram flow.mmd

Options:

Option	Description
`--theme <name>`	Theme name for styling
`-o`, `--output <path>`	Custom output file path

Examples:

# Render with a specific theme
agentpreso render-diagram architecture.mmd --theme corporate

# Custom output path
agentpreso render-diagram flow.mmd -o ./output/flow.svg

`agentpreso render-chart <file>`

Render a chart YAML file to SVG.

agentpreso render-chart revenue.yaml

Options:

Option	Description
`--theme <name>`	Theme name for styling
`-o`, `--output <path>`	Custom output file path

Examples:

# Render with a specific theme
agentpreso render-chart metrics.yaml --theme dark

# Custom output path
agentpreso render-chart revenue.yaml -o ./output/revenue.svg

Asset Commands

`agentpreso assets list`

List all uploaded assets.

agentpreso assets list

Options:

Option	Description
`--format <format>`	Output format: `table` or `json` (default: `table`)

Output:

ID        NAME              TYPE           SIZE
a1b2c3d4  hero-image.png    image/png      245KB
e5f6g7h8  logo.svg          image/svg+xml  12KB

`agentpreso assets upload <file>`

Upload a file as an asset. Returns an asset:// URI for use in presentations.

agentpreso assets upload ./images/hero.png

Options:

Option	Description
`--name <name>`	Custom filename for the asset

Examples:

# Upload with original filename
agentpreso assets upload ./logo.svg

# Upload with a custom name
agentpreso assets upload ./photo.jpg --name team-photo.jpg

`agentpreso assets delete <id>`

Delete an asset by ID.

agentpreso assets delete a1b2c3d4

Configuration Commands

`agentpreso config`

Show current configuration.

agentpreso config

`agentpreso config set <key> <value>`

Set a configuration value.

agentpreso config set defaults.theme corporate

Available settings:

Key	Description
`server.url`	API server URL
`defaults.theme`	Default theme for new decks
`defaults.format`	Default render format

`agentpreso config reset`

Reset configuration to defaults.

agentpreso config reset

Configuration Files

`~/.agentpreso/config.yaml`

Global configuration:

server:
  url: https://api.agentpreso.com
defaults:
  theme: minimal
  format: html

`~/.agentpreso/credentials`

API key storage (do not commit to version control):

api_key: ap_a1b2c3d4e5f6...

Exit Codes

Code	Description
`0`	Success
`1`	General error
`2`	Invalid arguments
`3`	Authentication required
`4`	Network error
`5`	File not found