Shipyard MCP

Shipyard CLI

用于管理 Shipyard 平台上临时环境的工具。

正在使用 AI 助手？CLI 内置了 MCP 服务：请参阅通过 AI 助手使用 Shipyard。

安装

• Linux 和 macOS

  curl https://www.shipyard.sh/install.sh | bash
  

  它会安装到 /usr/local/bin，只有在无法写入该目录时才会使用 sudo。若要安装到其他位置（例如你拥有的目录），请设置 SHIPYARD_INSTALL_DIR：

  curl https://www.shipyard.sh/install.sh | SHIPYARD_INSTALL_DIR="$HOME/.local/bin" bash
  

• Windows 前往发布页面，下载适用于 Windows 的可执行文件。

• Homebrew

  brew tap shipyard/tap
  brew install shipyard
  

验证下载文件

每次发布都会提供一个 checksums.txt，其中包含每个二进制文件的 SHA-256 值。安装脚本会据此检查二进制文件，若校验不匹配则拒绝安装。若要检查自行下载的二进制文件：

grep " shipyard-darwin-arm64$" checksums.txt | shasum -a 256 -c -

checksums.txt 与二进制文件来自同一次发布，因此它能检测下载文件是否损坏或不完整，但无法检测发布文件是否被替换。下方的证明信息用于确认二进制文件是由此仓库的发布工作流构建的。

在 1.9.0 之后的发布中，每个二进制文件还带有签名的构建来源证明，显示构建该文件的工作流运行、提交和标签；同时还提供 SPDX SBOM（shipyard-<os>-<arch>.sbom.json；Windows 上为 .exe.sbom.json），列出构建所用的内容。使用 GitHub CLI 验证证明信息，并指定下载的发布版本（此处为 v1.10.0）：

gh attestation verify shipyard-darwin-arm64 -R shipyard/shipyard-cli \
  --signer-workflow shipyard/shipyard-cli/.github/workflows/release.yaml \
  --source-ref refs/tags/v1.10.0

请保留 --source-ref：不加此参数时，任何分支上由工作流副本签名的内容都能通过检查，而不仅限于该发布标签对应的构建。

检查会验证标签，而不是对应的提交。撤回发布的证明信息不会被删除，因此如果某个版本后来再次以相同标签发布，其已撤回的二进制文件仍会通过验证。若要同时固定提交，请添加 --source-digest <commit SHA>，并指定该标签指向的提交。

升级

shipyard upgrade

shipyard update 执行相同操作。它会安装最新发布版本并显示发布说明。通过 Homebrew 安装的版本使用 brew upgrade shipyard 升级；其他安装方式则会下载发布二进制文件，根据发布中的 checksums.txt 进行验证，然后替换当前运行的二进制文件。如果该二进制文件位于你无权写入的目录（例如 /usr/local/bin），请运行 sudo shipyard upgrade。

添加 --prerelease 可包含预发布版本；添加 --force 可重新安装当前版本（Homebrew 安装则改用 brew reinstall shipyard）。

从 1.9.0 或更早版本升级

1.9.0 及更早版本中的 shipyard update 会将版本号按文本比较，因此会把 1.10.0 及之后的版本报告为比当前版本更旧。请按最初的安装方式升级一次，之后即可使用 shipyard upgrade：

• Linux 和 macOS： curl https://www.shipyard.sh/install.sh | bash
• Windows： 从发布页面下载可执行文件
• Homebrew： brew upgrade shipyard

更新通知

有新版本发布时，CLI 会在命令执行完毕后通知你，每天最多一次：

A new version of shipyard is available: 1.9.0 → 1.10.0
Run `shipyard upgrade` to install it. Release notes: https://github.com/shipyard/shipyard-cli/releases/tag/v1.10.0

它不会提出任何问题，也不会等待输入。检查会在命令运行期间于后台执行；如果命令结束时检查尚未完成，CLI 最多会等待一秒。只有在向 GitHub 发起请求时才会出现这种情况，例如每天检查一次，或获取你错过的发行说明。通过其他方式升级（例如运行 brew upgrade）后，首次运行时会显示这些说明。

该消息会发送到 stderr，且仅当 stderr 是终端时显示。在 CI、能够标识自身的 AI 编码 Agent（Claude Code、Codex、Cursor 的 Agent、Gemini CLI）中，以及运行 shipyard mcp serve 时，绝不会显示。若要关闭此功能，请设置 SHIPYARD_NO_UPDATE_CHECK=1，或在 ~/.shipyard/config.yaml 中添加 update_check: false。

登录

运行 shipyard login 初始化 CLI。系统会提示你在浏览器中登录 Shipyard。随后，CLI 会将你的 API 令牌保存到本地配置中。现在你就可以开始运行命令了。

或手动设置令牌

将 Shipyard API 令牌设为环境变量 SHIPYARD_API_TOKEN 的值。

你可以前往个人资料页面获取令牌。

如果你想为所在组织启用 API 访问权限，可以通过 [email protected] 联系我们。如果还有其他问题，欢迎加入我们的社区 Slack。

shipyard set token

或者，你可以使用默认存储在 $HOME/.shipyard/config.yaml 中的配置文件。首次运行 CLI 时，它会创建一个默认的空配置文件，你可以随后对其进行编辑。

你也可以在任意命令中添加 --config {path} 标志，以指定非默认的配置文件路径。

在配置文件中添加所需的配置值，并确保文件符合 YAML 语法。 例如：

api_token: <your-token>
org: <your-non-default-org>

环境变量的值会覆盖配置文件中对应的值。

基本用法

获取你所属的所有组织

shipyard get orgs

设置全局默认组织

shipyard set org {org-name}

获取当前配置的组织

shipyard get org

列出所有环境

shipyard get environments

可用标志：

名称	描述	类型	默认值
branch	按分支名称筛选	string
deleted	返回已删除的环境	boolean	false
json	打印完整的 JSON 输出	boolean	false
name	按应用程序名称筛选	string
org-name	如果你属于多个组织，则按组织名称筛选	string	你的默认组织
page	请求的页码	int	1
page-size	请求的页面大小	int	20
pull-request-number	按拉取请求编号筛选	string
repo-name	按仓库名称筛选	string

示例：

• 列出在 main 分支上运行仓库 flask-backend 的所有环境：

shipyard get environments --repo-name flask-backend --branch main

• 列出所有已删除的环境：

shipyard get environments --deleted

根据 UUID 获取特定环境的详细信息

shipyard get environment {environment_uuid}

可用标志：

名称	描述	类型	默认值
json	输出完整的 JSON 结果	boolean	false
org	环境所属的组织（如果你属于多个组织）	string	你的默认组织
bypass-token	仅输出环境的 bypass token，供脚本使用	boolean	false

--bypass-token 允许脚本使用令牌，而无需任何人手动输入或打印令牌：

SHIPYARD_TOKEN=$(shipyard get environment {environment_uuid} --bypass-token) && \
  export SHIPYARD_TOKEN && curl -b "shipyard_token=$SHIPYARD_TOKEN" https://your-environment-url/

停止正在运行的环境

shipyard stop environment {environment_uuid}

重启已停止的环境

shipyard restart environment {environment_uuid}

取消环境正在进行的构建

shipyard cancel environment {environment_uuid}

重新构建环境

shipyard rebuild environment {environment_uuid}

恢复已删除的环境

shipyard revive environment {environment_uuid}

部署分离环境

通过克隆现有应用构建，创建一个新的独立（“分离”）环境。 要求为你的组织启用分离环境。

shipyard detached deploy {application_build_uuid} --name my-detached-env

按仓库覆盖分支，并控制分离环境是否在有新提交时重新构建：

# Override the branch for a repo, and never rebuild on new commits
shipyard detached deploy {application_build_uuid} --name my-detached-env --branch web=feature-x --build-on-commit never

# Per-repo build-on-commit settings (always | inherit | never)
shipyard detached deploy {application_build_uuid} --build-on-commit-for web=always --build-on-commit-for api=never

获取环境中的所有服务和已公开端口

shipyard get services --env {environment_uuid}

执行进入正在运行的环境服务

在正在运行的环境中，针对指定服务执行任意命令，并传入任意参数和标志。双斜杠之后传入命令参数。

shipyard exec --env {environment_uuid} --service {service_name} -- bash

转发正在运行的环境服务端口

shipyard port-forward --env {environment_uuid} --service {service_name} --ports {local_port}:{service_container_port}

获取正在运行的环境服务日志

shipyard logs --env {environment_uuid} --service {service_name}

访问环境

shipyard visit {environment_uuid}

可用标志：

名称	描述	类型	默认值
follow	持续输出日志	boolean	false
tail	要显示的最近日志行数	int	3000

使用卷

列出环境中的所有卷

shipyard get volumes --env {environment_uuid}

列出环境中的所有卷快照

shipyard get snapshots --env {environment_uuid}

重置环境中的卷

shipyard reset volume --env {environment_uuid}

在环境中创建快照

shipyard create snapshot --env {environment_uuid}

在环境中加载卷快照

shipyard load snapshot --env {environment_uuid} --sequence-number {n}

将文件上传到环境中的卷

shipyard upload volume --env {environment_uuid} --volume {volume} --file {filepath.bz2}

直接调用 REST API

shipyard api /api/v1/environment
shipyard api -X PUT /api/v1/environment/{environment_uuid}/env-vars --input body.json

路径必须以 /api/v1 或 /api/v2 开头；系统会自动添加你的令牌和组织信息。 除非传入 --include-secrets，否则会对 bypass_token 和 kubeconfig 凭据进行脱敏。

连接到 telepresence

shipyard telepresence connect --env {environment_uuid}

之后，你就可以直接与命名空间中的所有 Pod 通信。你可能需要使用命名空间主机名与服务通信，可通过 telepresence status 的 Namespace 字段获取。例如，要与 redis 通信，你需要使用 redis.shipyard-app-build-{uuid}

从代码构建可执行文件：

运行以下命令即可创建可执行文件：

make

运行这个新建的可执行文件：

./shipyard

启用自动补全

Bash

此脚本依赖 bash-completion 软件包。如果尚未安装，可以通过操作系统的软件包管理器安装。 要在当前 Shell 会话中加载补全：

source <(shipyard completion bash)

要在每个新会话中加载补全，请执行以下命令一次。

在 Linux 上：

shipyard completion bash > /etc/bash_completion.d/shipyard

在 macOS 上：

shipyard completion bash > $(brew --prefix)/etc/bash_completion.d/shipyard

Zsh

如果你的环境尚未启用 Shell 补全，则需要先启用。执行以下命令一次即可：

echo "autoload -U compinit; compinit" >> ~/.zshrc

要在当前 Shell 会话中加载补全：

source <(shipyard completion zsh); compdef _shipyard shipyard

要在每个新会话中加载补全，请执行以下命令一次。

在 Linux 上：

shipyard completion zsh > "${fpath[1]}/_shipyard"

在 macOS 上：

shipyard completion zsh > $(brew --prefix)/share/zsh/site-functions/_shipyard

需要启动新的 Shell，此设置才会生效。

Fish

要在当前 Shell 会话中加载补全：

$ shipyard completion fish | source

要在每个会话中加载补全，请执行一次：

shipyard completion fish > ~/.config/fish/completions/shipyard.fish

PowerShell

要在当前 shell 会话中加载补全：

shipyard completion powershell | Out-String | Invoke-Expression

要在每个新会话中加载补全，请运行：

shipyard completion powershell > shipyard.ps1

并在 PowerShell 配置文件中引用此文件。

在 AI 助手中使用 Shipyard（MCP）

shipyard mcp serve 会运行一个 Model Context Protocol 服务，因此 Claude Code、Claude Desktop、Cursor 或 Codex 等助手可以列出、检查、重建和配置你的环境，读取服务日志、管理卷，并针对环境验证已推送的更改。

使用 CLI 登录后，将其添加到 Claude Code：

claude mcp add shipyard -- shipyard mcp serve

然后可以提出以下问题：

• “web 仓库有哪些环境正在运行？”
• “显示我的分支环境中 api 服务的日志。”
• “此环境的最新构建为什么失败？”
• “在此环境中设置 FEATURE_FLAGS=beta，并重启 worker 服务。”
• “我刚刚推送了更改。针对其环境验证此更改。”（或 /mcp__shipyard__verify）

请参阅 MCP 指南，了解如何在其他客户端中进行设置、配置、完整工具列表、verify 提示词以及故障排除。