shipfolio

English | 中文

What is shipfolio?

A CLI tool that turns your local projects into a personal portfolio website. It scans your git repositories, uses your local AI tools (Claude Code, Codex, or v0) to generate a production-ready Next.js site, and deploys it to Cloudflare Pages or Vercel -- all in one command.

Built for developers who ship fast and need a way to showcase their work without spending hours on a portfolio.

Quick Start

npx shipfolio --scan ~/Projects

The tool walks you through everything interactively: project selection, personal info, design preferences, and deployment.

Prerequisites

• Node.js >= 18
• At least one AI engine:

| Engine | How to get it | Notes | |---|---|---| | Claude Code | npm install -g @anthropic-ai/claude-code | Recommended. Best overall generation quality. | | Codex | npm install -g @openai/codex | Alternative. | | v0 | Set V0_API_KEY environment variable | Best UI design quality. Requires paid v0 plan. Get your key at v0.dev. |

No need to install wrangler or vercel CLI -- shipfolio calls them via npx automatically.

Commands

Generate a New Site

npx shipfolio --scan ~/Projects
npx shipfolio --scan ~/Projects --output ./my-site
npx shipfolio --scan ~/Projects --engine claude --deploy cloudflare --style dark-minimal --accent '#10b981'
npx shipfolio --scan ~/Projects --auto --no-pdf
npx shipfolio --scan ~/Projects --no-pdf --no-preview

The pipeline:

1. Scans directories for git repos (and non-git projects with package.json, Cargo.toml, etc.)
2. Interactive interview: select projects, optionally merge related ones (e.g. web + mobile), enter personal info, pick theme/colors/font, and optionally enrich key projects with case-study details
3. Generates the site using your local AI engine
4. Builds, previews locally, exports PDF
5. Deploys to Cloudflare Pages or Vercel
6. Optionally creates a GitHub repo with a CI/CD workflow for auto-deploy on push

Update an Existing Site

npx shipfolio update --site ./shipfolio-site
npx shipfolio update --site ./shipfolio-site --scan ~/Projects

Detects new/changed/removed projects and applies incremental updates. Preserves existing design, layout, and custom modifications.

Generate Spec Only

For use inside an existing Claude Code or Codex session:

npx shipfolio spec --scan ~/Projects --output ./

Outputs shipfolio-spec.json and shipfolio-prompt.md. Feed the prompt to your AI session to generate the site directly.

Deploy

npx shipfolio deploy --site ./shipfolio-site --platform cloudflare
npx shipfolio deploy --site ./shipfolio-site --platform vercel

Export PDF

npx shipfolio pdf --site ./shipfolio-site

Requires Playwright: npx playwright install chromium

Preview

npx shipfolio preview --site ./shipfolio-site --port 3000

CLI Reference

shipfolio init (default)

| Flag | Description | Default | |---|---|---| | -s, --scan <dirs...> | Directories to scan for projects | Current directory | | -e, --engine <name> | claude, codex, or v0 | Auto-detect | | -d, --deploy <platform> | cloudflare, vercel, or local | Prompted | | --style <theme> | dark-minimal, light-clean, monochrome, or custom | Prompted | | --accent <hex> | Accent color like #10b981 | Prompted | | --auto | Use safe defaults and skip prompts | false | | -o, --output <dir> | Output directory | ./shipfolio-site | | --no-pdf | Skip PDF export | | | --no-preview | Skip local preview | |

shipfolio update

| Flag | Description | |---|---| | --site <path> | Path to existing site directory (required) | | -s, --scan <dirs...> | Directories to scan | | --no-pdf | Skip PDF export | | --no-preview | Skip preview | | --no-deploy | Skip deployment |

shipfolio deploy

| Flag | Description | |---|---| | --site <path> | Path to site directory (required) | | -p, --platform <name> | cloudflare or vercel |

shipfolio spec

| Flag | Description | |---|---| | -s, --scan <dirs...> | Directories to scan | | -o, --output <dir> | Output directory for spec files |

shipfolio pdf

| Flag | Description | |---|---| | --site <path> | Path to site directory (required) | | -o, --output <path> | PDF output path |

shipfolio preview

| Flag | Description | |---|---| | --site <path> | Path to site directory (required) | | --port <port> | Port number (default: 3000, auto-fallback if in use) |

Features

Project Merging

When you have related projects (e.g. a web app and its mobile companion), shipfolio lets you merge them into a single portfolio entry. Tech stacks, commit histories, and READMEs are combined automatically, and update detection now tracks every merged project path instead of only the first one.

Featured Projects And Case Studies

You can mark projects as featured and optionally add richer case-study inputs such as audience, problem, solution, impact, evidence, and screenshot URLs. These fields are passed directly into the generation prompt so the resulting site can emphasize your strongest work instead of flattening every project into the same card style.

Draft Recovery

If the process crashes or you cancel after the interview step, your answers are saved to ~/.shipfolio/draft.json. Next time you run shipfolio, it offers to restore them.

i18n

The CLI detects your system locale. Chinese (zh-CN, zh-TW) users see Chinese prompts; everyone else sees English.

Custom Domain

During the deploy step, you can specify a custom domain. For Vercel, it is configured automatically via vercel domains add. For Cloudflare Pages, shipfolio prints a direct link to the dashboard with instructions.

GitHub Auto-Deploy

After deployment, shipfolio can create a GitHub repo and add a .github/workflows/deploy.yml that redeploys on every push. You just need to add one or two secrets to the repo:

Cloudflare Pages:

gh secret set CLOUDFLARE_API_TOKEN
gh secret set CLOUDFLARE_ACCOUNT_ID

Vercel:

gh secret set VERCEL_TOKEN

Generated Site Stack

• Next.js 15 (App Router, static export output: 'export')
• Tailwind CSS v4
• shadcn/ui components
• TypeScript
• Responsive (desktop + tablet + mobile)
• Print-optimized CSS for PDF export
• Build output: static out/ directory

Deployment Platforms

Cloudflare Pages

No CLI pre-install needed. On first run, npx wrangler login opens a browser for authentication. The project is auto-created. Your site gets a <project-name>.pages.dev URL.

Free tier: unlimited sites, 500 builds/month, unlimited bandwidth.

Vercel

No CLI pre-install needed. On first run, npx vercel login opens a browser for authentication. Your site gets a <project-name>.vercel.app URL.

Links

• GitHub: github.com/Octo-o-o-o/shipfolio
• npm: npmjs.com/package/shipfolio
• Issues: github.com/Octo-o-o-o/shipfolio/issues

License

MIT

shipfolio 是什么?

一个 CLI 工具，将你本地的项目转化为个人作品集网站。它扫描你的 git 仓库，使用你本地的 AI 工具（Claude Code、Codex 或 v0）生成生产级 Next.js 网站，并一键部署到 Cloudflare Pages 或 Vercel。

为快速交付项目但没时间做作品集的开发者而建。

快速开始

npx shipfolio --scan ~/Projects

工具会以交互方式引导你完成所有步骤：项目选择、个人信息、设计偏好、部署。

前置条件

• Node.js >= 18
• 至少一个 AI 引擎:

| 引擎 | 安装方式 | 说明 | |---|---|---| | Claude Code | npm install -g @anthropic-ai/claude-code | 推荐。综合生成质量最佳。 | | Codex | npm install -g @openai/codex | 备选。 | | v0 | 设置 V0_API_KEY 环境变量 | UI 设计质量最佳。需要 v0 付费订阅。在 v0.dev 获取 API key。 |

不需要预装 wrangler 或 vercel CLI -- shipfolio 通过 npx 自动调用。

命令

生成新网站

npx shipfolio --scan ~/Projects
npx shipfolio --scan ~/Projects --output ./my-site
npx shipfolio --scan ~/Projects --engine claude --deploy cloudflare --style dark-minimal --accent '#10b981'
npx shipfolio --scan ~/Projects --auto --no-pdf
npx shipfolio --scan ~/Projects --no-pdf --no-preview

流程:

1. 扫描目录中的 git 仓库（也支持没有 git 但有 package.json、Cargo.toml 等的项目）
2. 交互式问答：选择项目、可选合并相关项目（如 web + mobile）、填写个人信息、选择主题/颜色/字体，并可为重点项目补充更完整的案例信息
3. 调用本地 AI 引擎生成网站
4. 构建、本地预览、导出 PDF
5. 部署到 Cloudflare Pages 或 Vercel
6. 可选创建 GitHub 仓库并配置 CI/CD workflow，实现 push 自动部署

更新已有网站

npx shipfolio update --site ./shipfolio-site
npx shipfolio update --site ./shipfolio-site --scan ~/Projects

检测新增/变更/移除的项目，增量更新。保留现有设计、布局和自定义修改。

仅生成 Spec

在 Claude Code 或 Codex 会话中使用:

npx shipfolio spec --scan ~/Projects --output ./

输出 shipfolio-spec.json 和 shipfolio-prompt.md。将 prompt 输入 AI 会话即可直接生成网站。

部署

npx shipfolio deploy --site ./shipfolio-site --platform cloudflare
npx shipfolio deploy --site ./shipfolio-site --platform vercel

导出 PDF

npx shipfolio pdf --site ./shipfolio-site

需要 Playwright: npx playwright install chromium

本地预览

npx shipfolio preview --site ./shipfolio-site --port 3000

CLI 参考

shipfolio init（默认命令）

| 参数 | 说明 | 默认值 | |---|---|---| | -s, --scan <dirs...> | 扫描目录 | 当前目录 | | -e, --engine <name> | claude、codex 或 v0 | 自动检测 | | -d, --deploy <platform> | cloudflare、vercel 或 local | 交互选择 | | --style <theme> | dark-minimal、light-clean、monochrome 或 custom | 交互选择 | | --accent <hex> | 强调色，如 #10b981 | 交互选择 | | --auto | 使用安全默认值并跳过问答 | false | | -o, --output <dir> | 输出目录 | ./shipfolio-site | | --no-pdf | 跳过 PDF 导出 | | | --no-preview | 跳过本地预览 | |

shipfolio update

| 参数 | 说明 | |---|---| | --site <path> | 已有网站目录（必填） | | -s, --scan <dirs...> | 扫描目录 | | --no-pdf | 跳过 PDF 导出 | | --no-preview | 跳过预览 | | --no-deploy | 跳过部署 |

shipfolio deploy

| 参数 | 说明 | |---|---| | --site <path> | 网站目录（必填） | | -p, --platform <name> | cloudflare 或 vercel |

shipfolio spec

| 参数 | 说明 | |---|---| | -s, --scan <dirs...> | 扫描目录 | | -o, --output <dir> | Spec 文件输出目录 |

shipfolio pdf

| 参数 | 说明 | |---|---| | --site <path> | 网站目录（必填） | | -o, --output <path> | PDF 输出路径 |

shipfolio preview

| 参数 | 说明 | |---|---| | --site <path> | 网站目录（必填） | | --port <port> | 端口号（默认 3000，占用时自动切换） |

功能特性

项目合并

当你有关联项目时（如 web 端和 mobile 端），shipfolio 支持将它们合并为一个作品集条目。技术栈、提交历史和 README 会自动合并；更新检测也会追踪所有被合并项目的路径，不再只看第一个目录。

重点项目与案例信息

你可以把项目标记为重点项目，并可选补充 audience、problem、solution、impact、evidence、screenshot URL 等案例信息。这些结构化字段会直接进入生成 prompt，让最终网站更容易突出真正重要的作品，而不是把所有项目都做成同一种平铺卡片。

草稿恢复

如果流程中断或在问答环节后崩溃，你的回答会保存到 ~/.shipfolio/draft.json。下次运行时会询问是否恢复。

多语言

CLI 自动检测系统语言。简体中文和繁体中文用户看到中文提示，其他语言看到英文。

自定义域名

部署时可指定自定义域名。Vercel 通过 vercel domains add 自动配置。Cloudflare Pages 会打印 dashboard 直链和操作指引。

GitHub 自动部署

部署后，shipfolio 可创建 GitHub 仓库并添加 .github/workflows/deploy.yml，每次 push 自动重新部署。只需在仓库中添加 secrets:

Cloudflare Pages:

gh secret set CLOUDFLARE_API_TOKEN
gh secret set CLOUDFLARE_ACCOUNT_ID

Vercel:

gh secret set VERCEL_TOKEN

生成的网站技术栈

• Next.js 15 (App Router, 静态导出 output: 'export')
• Tailwind CSS v4
• shadcn/ui 组件
• TypeScript
• 响应式（桌面 + 平板 + 移动端）
• PDF 导出优化的打印样式
• 构建产物：纯静态 out/ 目录

部署平台

Cloudflare Pages

不需要预装 CLI。首次运行时 npx wrangler login 会打开浏览器进行认证。项目自动创建。网站获得 <项目名>.pages.dev 域名。

免费额度: 无限站点，500 次构建/月，无限带宽。

Vercel

不需要预装 CLI。首次运行时 npx vercel login 会打开浏览器进行认证。网站获得 <项目名>.vercel.app 域名。

相关链接

• GitHub: github.com/Octo-o-o-o/shipfolio
• npm: npmjs.com/package/shipfolio
• 问题反馈: github.com/Octo-o-o-o/shipfolio/issues

许可证

MIT