PreviewShip Documentation

PreviewShip turns browser-ready frontend artifacts into fixed preview URLs. Choose the method that fits your workflow:

1. 1Register a free account at previewship.com
2. 2Create an API Key in the console (API Keys page)
3. 3Deploy React/Vue/Vite/Next static output, a zip with index.html, a single HTML/Markdown/PDF file, pasted HTML, or agent-generated output via CLI, MCP, editor extension, or console upload
4. 4Share the fixed preview URL, then manage access, versions, rollback, redeploy, or project cleanup when needed

Use PreviewShip when the browser can already open the artifact you want to share. It is built for frontend review links, not source-code builds or backend hosting.

Deploy from the terminal with one command, then manage fixed project URLs, public/password access, versions, rollback, redeploy, and deletion. The CLI also supports JSON output for AI agents and CI.

Install

Use npx directly (no install needed) or install globally:

Set API Key

Set your API Key for authentication:

Or set via environment variable:

Deploy

Deploy a built static directory or a single HTML, Markdown, or PDF document to get a preview link:

JSON Output for Agents

Use --json flag for structured output, ideal for AI agents and CI pipelines:

Project management commands

Use these commands when you need to inspect projects, change access, restore an expired link, roll back the fixed URL, or delete an unused Free project slot.

previewship deployments list --json
previewship projects list --json
previewship projects access 42 --password "review-pass"
previewship projects access 42 --public
previewship projects versions 42
previewship projects rollback 42 105 --confirm my-project
previewship projects redeploy 42
previewship projects delete 42 --confirm my-project

The MCP server lets AI coding agents deploy previews and manage projects as native tool calls. Works with Claude Code, Cursor, Windsurf, and any MCP-compatible client.

Configuration

For Claude Code, add to ~/.claude/settings.json:

{
  "mcpServers": {
    "previewship": {
      "command": "npx",
      "args": ["-y", "previewship-mcp"],
      "env": {
        "PREVIEWSHIP_API_KEY": "ps_live_your_key_here"
      }
    }
  }
}

For Cursor, create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "previewship": {
      "command": "npx",
      "args": ["-y", "previewship-mcp"],
      "env": {
        "PREVIEWSHIP_API_KEY": "ps_live_your_key_here"
      }
    }
  }
}

For Windsurf, add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "previewship": {
      "command": "npx",
      "args": ["-y", "previewship-mcp"],
      "env": {
        "PREVIEWSHIP_API_KEY": "ps_live_your_key_here"
      }
    }
  }
}

Available Tools

• deploy_preview — Deploy a build-output directory or a single HTML, Markdown, or PDF document and get a fixed preview URL
• check_deployment — Check deployment status by ID
• show_usage — Show remaining deployment quota
• list_projects / get_project — Inspect fixed URLs, project status, access mode, and redeploy availability
• get_project_access / set_project_access — Switch between PUBLIC and PASSWORD; PUBLIC clears the saved password
• list_project_versions / rollback_project_version — Show retained versions and roll a fixed URL back to a historical deployment
• redeploy_project_latest — Restore an expired fixed preview link from the latest retained artifact
• delete_project — Delete a confirmed project and permanently remove its fixed URL, hosted project, deployment association, and Showcase entry

PreviewShip also provides an optional Codex skill for sharing the current Codex conversation. It turns the visible chat transcript into a high-fidelity HTML page, deploys it with the PreviewShip CLI, and returns a public URL.

Install the skill

Use in Codex

After installation, reference the skill in a Codex conversation:

PreviewShip also provides an optional Claude Code skill for sharing Claude Code conversations. It reads local Claude Code JSONL history, renders the visible chat into a high-fidelity HTML page, deploys it with the PreviewShip CLI, and returns a public URL.

Install the skill

Use in Codex

After installation, reference the skill from Codex and ask it to share a Claude Code conversation:

Cursor is fully compatible with VS Code extensions. You can install PreviewShip the same way.

Install via Command Palette

1. 1Open Cursor, press Ctrl+P (Cmd+P on Mac)
2. 2Paste the command below and press Enter:

Install via VSIX

If you prefer offline installation, download the .vsix file and follow the "Manual VSIX Install" section below.

Open VS Code, press Ctrl+P (Cmd+P on Mac), paste the command below and press Enter:

If the marketplace is unavailable in your environment, you can install the extension manually via a .vsix file.

Installation Steps

1. 1Download the .vsix file using the button above
2. 2Open Cursor or VS Code, go to Extensions panel (Ctrl+Shift+X)
3. 3Click "..." in the top-right of the Extensions panel → "Install from VSIX..." → select the downloaded file

Alternatively, install via command line:

An API Key is required for all deployment methods (CLI, MCP, editor extension). Here's how to create one:

1. 1Log in to previewship.com and go to the API Keys page
2. 2Click "Create API Key", give it a name, and copy the generated key
3. 3Use the key in CLI (previewship login), MCP config (PREVIEWSHIP_API_KEY env var), or editor extension (Set API Key command)

Once the extension is installed and your API Key is set:

1. 1Open your frontend project folder in the editor
2. 2Open the command palette (Ctrl+Shift+P) and run "PreviewShip: Deploy Workspace, HTML, Markdown, or PDF File" or "PreviewShip: Deploy Active HTML, Markdown, or PDF File"
3. 3The extension packages the selected build output, HTML, Markdown, or PDF file, uploads it, and returns a preview URL when ready

You can also deploy directly from the web console without any tools. The console supports uploading a build-output zip, uploading a single HTML, Markdown, or PDF file, or pasting HTML source:

1. 1Log in and go to the Deploy page
2. 2Select or create a project, then upload a .zip containing static build output, upload a .html/.md/.markdown/.pdf file, or paste a complete HTML document
3. 3PreviewShip deploys zip artifacts as static sites, packages single HTML input as index.html, adds a safe viewer for Markdown, and adds a redirect entry that opens PDF in the full-screen browser-native viewer

Projects are the stable container behind PreviewShip links. Each project owns a fixed URL, a latest deployment pointer, access mode, retained versions, and optional Showcase state.

• Projects are created automatically when you deploy with a new project name, including claimed guest previews.
• The fixed project URL does not change on each deploy; deployments and rollbacks update what that URL serves.
• Public projects can be shared normally. Pro projects can use password access; switching back to public clears the password.
• Version history is plan-based: Free keeps 3 rollback-capable versions, Pro Monthly keeps 10, and Pro Yearly keeps 40 when artifacts are retained.
• Free includes 1 project. If the limit is full, delete an unused project or upgrade before deploying or claiming another preview.
• Deleting a project removes the fixed preview URL, hosted project, deployment association, and Showcase entry permanently.
• Only public, share-approved Showcase items can be indexed. Password projects, private or hidden items, and expired inaccessible content stay out of sitemap indexing.

PreviewShip plans combine deploy quota, project count, upload allowance, retention, version history, access control, and watermark removal: