Shipyard

Shipyard CLI

一個用於在 Shipyard 平台上管理臨時環境（Ephemeral Environments）的工具。

正在使用 AI 助手？CLI 包含一個 MCP 伺服器：請參閱從 AI 助手使用 Shipyard。

安裝

• Linux 和 macOS

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

• Windows 前往發布頁面下載 Windows 的可執行檔。

• Homebrew

  brew tap shipyard/tap
  brew install shipyard
  

登入

執行 shipyard login 來初始化 CLI。這會提示您在瀏覽器中登入 Shipyard。CLI 接著會將您的 API token 儲存在本機設定檔中。您就可以開始執行指令了。

或手動設定您的 Token

將您的 Shipyard API token 設定為 SHIPYARD_API_TOKEN 環境變數的值。

您可以前往您的個人資料頁面取得。

如果您想為您的組織啟用 API 存取，可以透過 support@shipyard.build 與我們聯繫。如果您有任何其他問題，歡迎加入我們的社群 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	依 pull request 編號篩選	string
repo-name	依儲存庫名稱篩選	string

範例：

• 列出在 flask-backend 儲存庫的 main 分支上執行的所有環境：

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 讓腳本可以使用 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 開頭；您的 token 和組織會自動加入。 bypass_token 和 kubeconfig 憑證會被遮蔽，除非您傳遞 --include-secrets。

連線到 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 儲存庫有哪些環境在執行？」
• 「顯示我分支環境上 api 服務的日誌。」
• 「在此環境上設定 FEATURE_FLAGS=beta 並重新啟動 worker 服務。」
• 「我剛剛推送了。驗證變更是否對應其環境。」（或 /mcp__shipyard__verify）

請參閱 MCP 指南 以了解在其他用戶端中進行設定、設定、完整工具清單、verify 提示詞以及疑難排解。