Shipyard

官方

Shipyard CLI 提供了一個 MCP 伺服器，讓代理程式能直接管理 Shipyard 環境：包括拉取日誌、比較分支、執行測試，以及停止/啟動環境。

GitHub

你可以用 Shipyard MCP 做什麼？

列出環境 — 詢問目前有哪些環境正在執行，可依 repo、branch、pull request 編號或名稱篩選。
檢查環境 — 依 UUID 取得特定環境的詳細資訊，包括其服務和公開連接埠。
讀取服務日誌 — 顯示執行中環境內某項服務的日誌，也可選擇持續追蹤輸出。
管理環境生命週期 — 依 UUID 停止、重新啟動、取消、重建或復原環境。
設定環境變數 — 在環境中設定 env vars，並重新啟動服務以套用變更。
驗證已推送的變更 — 使用 verify 提示詞檢查已推送的變更及其環境。

文件

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>，並指定該標籤所指向的提交。

重建發行版本

1.10.0 之後的發行版本都可重現：使用相同版本的 Go 和 GoReleaser，再次建置發行版本標籤，無論在哪個目錄中，都會產生位元組完全相同的二進位檔。這些版本是該標籤的 .github/workflows/release.yaml 中的 GO_VERSION 和 GORELEASER_VERSION。安裝好該版本的 GoReleaser，並在下方以 1.26.11 取代 GO_VERSION（GOTOOLCHAIN 會讓 Go 使用該指定版本，需要時會下載；GOFLAGS= 則會移除您自行設定的任何建置旗標）：

git clone https://github.com/shipyard/shipyard-cli && cd shipyard-cli
git checkout vX.Y.Z
GOTOOLCHAIN=go1.26.11 GOFLAGS= goreleaser release --clean --skip=publish,sbom
grep " shipyard-linux-amd64$" dist/checksums.txt

摘要應與發行版本的 checksums.txt 中相同那一行相符。若不相符，請先檢查 Go 和 GoReleaser 版本（GOTOOLCHAIN=go1.26.11 go version、goreleaser --version），再懷疑發行版本有問題。發行工作流程會在每個發行提交上、建置發行版本之前檢查這一點（scripts/check-reproducible.sh）。SBOM 無法重現：它們會記錄產生時間。CLI 自身模組的項目會顯示版本 (devel)，因為建置時會省略 Go 的 VCS 標記；shipyard --version 會印出發行版本。

升級

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 程式碼代理（Claude Code、Codex、Cursor 的 agent、Gemini CLI）中，或使用 shipyard mcp serve 時，絕不會顯示。若要關閉通知，請設定 SHIPYARD_NO_UPDATE_CHECK=1，或將 update_check: false 加入 ~/.shipyard/config.yaml。

關閉自動更新

在無法連線至 GitHub 的自架 Shipyard 上，CLI 會隨 Shipyard 發行版本一同提供。請在 ~/.shipyard/config.yaml 中設定 self_update: false，或設定 SHIPYARD_SELF_UPDATE=false，以關閉自動更新。此後 CLI 絕不會連線至 GitHub：不會顯示更新通知、shipyard mcp serve 不會在背景檢查，而 shipyard upgrade 會拒絕執行並顯示自動更新已關閉的訊息。update_check: false 只會關閉通知和背景檢查。

基本用法

取得您所屬的所有組織

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

刪除分離式環境

傳入環境 UUID，或其任一應用程式建置的 UUID（位於建置詳細資料頁面的 URL 中）。只有分離式環境能以此方式刪除；基礎環境、提取要求環境或遠端環境都會遭到拒絕。再次刪除已刪除的環境也會成功。

shipyard detached delete {environment_uuid}
shipyard detached delete {application_build_uuid}

取得環境的所有服務和公開連接埠

shipyard get services --env {environment_uuid}

進入執行中環境的服務並執行指令

在執行中環境的指定服務中，執行任何指令及其任何引數和旗標。請在雙斜線後傳入指令引數。只有在您於工作階段中輸入內容時，環境才不會因閒置而停止，最長可達 12 小時。

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

轉送執行中環境服務的連接埠

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

開啟的 port-forward 或 logs --follow 最多可讓環境維持執行 12 小時，避免因閒置而停止。

取得執行中環境服務的記錄

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 通訊。你_可能_需要使用命名空間主機名稱與服務通訊；你可以在 Namespace 欄位下方透過 telepresence status 取得該名稱。例如，若要與 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 repo 中有哪些環境正在執行？」
「顯示我分支環境中 api 服務的記錄。」
「這個環境最近一次建置為什麼失敗？」
「在這個環境設定 FEATURE_FLAGS=beta，並重新啟動 worker 服務。」
「我剛推送了變更。請在其環境中驗證這項變更。」（或 /mcp__shipyard__verify）

請參閱 MCP 指南，了解如何在其他用戶端中設定、進行組態設定、查看完整工具清單、使用 verify 提示，以及排解問題。

Shipyard

你可以用 Shipyard MCP 做什麼？

文件

Shipyard CLI

安裝

驗證下載檔案

重建發行版本

升級

從 1.9.0 或更早版本升級

更新通知

關閉自動更新

登入

自架 Shipyard

或手動設定權杖

基本用法

取得您所屬的所有組織

設定全域預設組織

取得目前設定的組織

列出所有環境

依 UUID 取得特定環境的詳細資料

停止執行中的環境

重新啟動已停止的環境

取消環境正在進行的建置

重建環境

復原已刪除的環境

部署分離式環境

刪除分離式環境

取得環境的所有服務和公開連接埠

進入執行中環境的服務並執行指令

轉送執行中環境服務的連接埠

取得執行中環境服務的記錄

瀏覽環境

使用磁碟區

列出環境中的所有磁碟區

列出環境中的所有磁碟區快照

重設環境中的磁碟區

在環境中建立快照

在環境中載入磁碟區快照

將檔案上傳至環境中的磁碟區

直接呼叫 REST API

連線至 telepresence

從程式碼建置可執行檔：

啟用自動補全

Bash

Zsh

Fish

PowerShell

從 AI 助理使用 Shipyard（MCP）