vslides CLI

Command-line interface for creating and managing Vercel Slides presentations.

Installation

npm install -g vslides

Or run directly with npx:

npx vslides <command>

Quick Start

# First time: Login to save credentials (valid for 7 days)
vslides login

# Create a new presentation
vslides init

# Wait for sandbox to be ready
vslides check --wait

# Edit slides.md, then push changes
vslides push

# Open preview in browser
vslides preview --open

Authentication

The CLI uses persistent authentication so you don't need to re-authenticate for every new presentation.

Commands

vslides login

Authenticate with your Vercel account. Opens a browser for OAuth authentication. Credentials are cached locally and valid for 7 days.

vslides login
# Opens browser for Vercel OAuth
# Credentials saved to ~/.vslides/auth.json

vslides logout

Sign out and revoke your cached credentials.

vslides logout

vslides whoami

Show your current authentication status.

vslides whoami
# Output: Logged in as [email protected]
#         Expires: 2/4/2026 (7 days remaining)

# Validate token with server
vslides whoami --validate

How Authentication Works

1. First-time setup: Run vslides login to authenticate via Vercel OAuth
2. Credentials cached: Token stored in ~/.vslides/auth.json (valid for 7 days)
3. Automatic use: vslides init uses cached credentials to skip OAuth flow
4. Expiration: After 7 days, run vslides login again

Security

• Credentials stored in ~/.vslides/auth.json with restricted permissions (600)
• Directory ~/.vslides/ created with mode 700
• Tokens can be revoked server-side via vslides logout
• Only @vercel.com email addresses are authorized

Session Management

vslides init

Create a new presentation session. If you're logged in, the session is created immediately without OAuth. Otherwise, you'll need to authenticate in the browser.

vslides init
# If logged in: Creates authenticated session immediately
# If not logged in: Provides AUTH_URL for browser authentication

Output files created:

• .vslides.json - Session configuration (do not commit)
• .vslides-guide.md - Layout reference guide
• slides.md - Your presentation (starter template if none exists)

vslides check

Check session status. Use --wait to poll until the sandbox is ready.

# Check current status
vslides check

# Wait for sandbox to be ready (60s timeout)
vslides check --wait

# Run in background
vslides check --wait &

vslides preview

Show or open the preview URL.

# Print preview URL
vslides preview

# Open in browser
vslides preview --open

Content Management

vslides push

Upload your local slides.md to the server.

# Push changes
vslides push

# Force push (bypass version check)
vslides push --force

vslides get

Download the current slides from the server.

vslides get

vslides sync

Smart bidirectional sync. Checks for remote changes before pushing.

vslides sync

vslides guide

Print the slide layout guide.

# Print cached guide
vslides guide

# Force refresh from server
vslides guide --refresh

Collaboration

vslides share

Get a join URL for collaborators.

vslides share
# Output: JOIN_URL: https://...

vslides join <url>

Join a shared session.

vslides join https://slidev-server.vercel.app/join/abc123

Assets

vslides upload <file>

Upload an image or media file.

vslides upload logo.png
# Output: Use in slides as:
#   image: /assets/logo.png

Supported formats: .jpg, .jpeg, .png, .gif, .svg, .webp, .ico

Export

vslides export <format>

Export presentation to PDF or PPTX.

vslides export pdf
vslides export pptx

Deploy

vslides deploy

Deploy presentation as a permanent static site. The deployed URL works without the sandbox running and loads faster.

vslides deploy
# Output:
# DEPLOYED: https://slidev-server.vercel.app/static/happy-blue-ocean
# VERSION: 5
# DEPLOYED_AT: 2026-01-28T12:00:00.000Z

Benefits:

• Permanent URL that doesn't expire
• Fast loading (no sandbox startup)
• Works even after sandbox times out
• Can be embedded in docs/wikis

Version History

vslides history

List saved versions.

vslides history
# Output:
# VERSION  TIMESTAMP
# 3        2026-01-28 10:30:00
# 2        2026-01-28 10:15:00
# 1        2026-01-28 10:00:00

vslides revert <version>

Revert to a previous version.

vslides revert 2

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | VSLIDES_API_URL | API server URL | https://slidev-server.vercel.app |

Files

| File | Location | Description | |------|----------|-------------| | auth.json | ~/.vslides/ | Cached authentication credentials | | .vslides.json | Project directory | Session configuration | | .vslides-guide.md | Project directory | Layout reference guide | | slides.md | Project directory | Your presentation |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Conflict (version mismatch, not running) | | 2 | Authentication required | | 3 | Network error | | 4 | Validation error |

Troubleshooting

"Session expired" error

Your authentication has expired. Run:

vslides login
vslides init

"Not authenticated" error

You need to complete the OAuth flow:

vslides check --wait &
# Open AUTH_URL in browser and authenticate

Version conflict

Another collaborator pushed changes. Run:

vslides get
# Review changes in slides.md
vslides push

Or use sync for automatic handling:

vslides sync

Sandbox timeout

Sessions expire after 45 minutes of inactivity. Create a new session:

rm .vslides.json
vslides init

Slide Format

Slides use Markdown with YAML frontmatter:

---
title: My Presentation
---

---
layout: 1-title
variant: title
---

# Welcome

Your presentation starts here

---
layout: 2-statement
variant: large
---

# Make a Statement

This is where your content goes

Run vslides guide for the complete layout reference.