Shipyard

Shipyard CLI

Công cụ để quản lý Ephemeral Environments trên nền tảng Shipyard.

Bạn đang dùng trợ lý AI? CLI có tích hợp máy chủ MCP: xem Sử dụng Shipyard từ trợ lý AI.

Cài đặt

• Linux và macOS

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

  Công cụ được cài đặt vào /usr/local/bin, chỉ dùng sudo nếu không thể ghi vào đó. Để cài đặt ở nơi khác, chẳng hạn như một thư mục bạn sở hữu, hãy đặt SHIPYARD_INSTALL_DIR:

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

• Windows Truy cập trang phát hành và tải xuống tệp thực thi dành cho Windows.

• Homebrew

  brew tap shipyard/tap
  brew install shipyard
  

Xác minh bản tải xuống

Mỗi bản phát hành đều cung cấp một checksums.txt chứa SHA-256 của từng tệp nhị phân. Tập lệnh cài đặt kiểm tra tệp nhị phân đối chiếu với giá trị này và từ chối cài đặt nếu không khớp. Để kiểm tra tệp nhị phân bạn tự tải xuống:

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

checksums.txt được lấy từ cùng bản phát hành với tệp nhị phân, nên nó phát hiện bản tải xuống bị hỏng hoặc không đầy đủ, chứ không phát hiện bản phát hành có các tệp bị thay thế. Chứng thực bên dưới xác minh rằng tệp nhị phân được tạo bởi quy trình phát hành của repo này.

Trong các bản phát hành sau 1.9.0, mỗi tệp nhị phân còn có chứng thực nguồn gốc bản dựng được ký, cho biết quy trình làm việc, commit và tag nào đã tạo ra nó, cùng với SBOM SPDX (shipyard-<os>-<arch>.sbom.json; .exe.sbom.json trên Windows) liệt kê các thành phần được dùng để tạo bản dựng. Xác minh chứng thực bằng GitHub CLI, chỉ định bản phát hành bạn đã tải xuống (ở đây là 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

Giữ nguyên --source-ref: nếu không có nó, bước kiểm tra sẽ chấp nhận mọi thứ được bản sao của quy trình làm việc ký trên bất kỳ nhánh nào, chứ không chỉ bản dựng tag của bản phát hành đó.

Bước kiểm tra xác định tag, chứ không phải commit của tag. Chứng thực của bản phát hành đã rút lại không bị xóa, vì vậy nếu một phiên bản được phát hành lại dưới cùng tag, các tệp nhị phân đã rút lại của phiên bản đó vẫn vượt qua bước kiểm tra. Để cố định cả commit, hãy thêm --source-digest <commit SHA> cùng với commit mà tag trỏ tới.

Tạo lại bản phát hành

Các bản phát hành sau 1.10.0 có thể tái tạo: tạo bản dựng lại tag phát hành bằng cùng phiên bản Go và GoReleaser sẽ cho ra các tệp nhị phân giống hệt từng byte trong mọi thư mục. Các phiên bản được ghi trong GO_VERSION và GORELEASER_VERSION thuộc .github/workflows/release.yaml của tag đó. Khi đã cài đặt GoReleaser này và thay 1.26.11 bên dưới bằng GO_VERSION (GOTOOLCHAIN khiến Go sử dụng chính xác phiên bản đó, tải xuống nếu cần, còn GOFLAGS= loại bỏ mọi cờ bản dựng do bạn tự đặt):

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

Giá trị digest phải khớp với cùng dòng trong checksums.txt của bản phát hành. Nếu không khớp, hãy kiểm tra phiên bản Go và GoReleaser của bạn (GOTOOLCHAIN=go1.26.11 go version, goreleaser --version) trước khi nghi ngờ bản phát hành. Quy trình phát hành kiểm tra điều này trên mỗi commit phát hành trước khi tạo bản dựng phát hành (scripts/check-reproducible.sh). SBOM không thể tái tạo: chúng ghi lại thời điểm được tạo. Mục dành cho module của chính CLI hiển thị phiên bản (devel), vì bản dựng không bao gồm dấu VCS của Go; shipyard --version in ra phiên bản phát hành.

Nâng cấp

shipyard upgrade

shipyard update thực hiện tương tự. Lệnh này cài đặt bản phát hành mới nhất và hiển thị ghi chú phát hành. Bản cài đặt Homebrew được nâng cấp bằng brew upgrade shipyard; các bản cài đặt khác sẽ tải xuống tệp nhị phân của bản phát hành, xác minh tệp đó với checksums.txt của bản phát hành rồi thay thế tệp nhị phân đang chạy. Nếu tệp nhị phân nằm trong thư mục bạn không có quyền ghi, chẳng hạn như /usr/local/bin, hãy chạy sudo shipyard upgrade.

Thêm --prerelease để bao gồm các bản phát hành trước, hoặc --force để cài đặt lại bản phát hành hiện tại (với bản cài đặt Homebrew, hãy dùng brew reinstall shipyard thay thế).

Nâng cấp từ phiên bản 1.9.0 trở xuống

shipyard update trong phiên bản 1.9.0 trở xuống so sánh phiên bản dưới dạng văn bản, nên báo phiên bản 1.10.0 trở lên cũ hơn phiên bản bạn đang dùng. Hãy nâng cấp một lần theo cách bạn đã cài đặt; từ đó trở đi, shipyard upgrade sẽ hoạt động:

• Linux và macOS: curl https://www.shipyard.sh/install.sh | bash
• Windows: tải xuống tệp thực thi từ trang phát hành
• Homebrew: brew upgrade shipyard

Thông báo cập nhật

Khi có bản phát hành mới, CLI sẽ thông báo sau khi một lệnh hoàn tất, tối đa một lần mỗi ngày:

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 không bao giờ hỏi gì hoặc chờ nhập liệu. Việc kiểm tra chạy nền trong khi lệnh của bạn đang chạy; nếu chưa hoàn tất khi lệnh kết thúc, CLI sẽ chờ tối đa một giây. Điều này chỉ xảy ra khi CLI đang truy vấn GitHub, khoảng một lần mỗi ngày hoặc để tải ghi chú phát hành mà bạn chưa xem. Lần chạy đầu tiên sau khi nâng cấp bằng cách khác, chẳng hạn như brew upgrade, sẽ hiển thị các ghi chú đó.

Thông báo được gửi đến stderr và chỉ hiển thị khi stderr là một terminal. Thông báo không bao giờ xuất hiện trong CI, bên trong các tác nhân lập trình AI tự nhận diện (Claude Code, Codex, tác nhân của Cursor, Gemini CLI), hoặc khi dùng shipyard mcp serve. Để tắt thông báo, hãy đặt SHIPYARD_NO_UPDATE_CHECK=1 hoặc thêm update_check: false vào ~/.shipyard/config.yaml.

Tắt tính năng tự cập nhật

Trên Shipyard tự lưu trữ không thể kết nối với GitHub, CLI được cung cấp cùng bản phát hành Shipyard của bạn. Tắt tính năng tự cập nhật tại đó bằng cách đặt self_update: false trong ~/.shipyard/config.yaml, hoặc SHIPYARD_SELF_UPDATE=false. Khi đó, CLI sẽ không bao giờ liên hệ với GitHub: không có thông báo cập nhật, không có kiểm tra nền từ shipyard mcp serve, và shipyard upgrade sẽ từ chối thực hiện kèm thông báo rằng tính năng tự cập nhật đã tắt. update_check: false chỉ tắt thông báo và kiểm tra nền.

Đăng nhập

Chạy shipyard login để khởi tạo CLI. Lệnh này sẽ nhắc bạn đăng nhập vào Shipyard trong trình duyệt. Sau đó, CLI sẽ lưu token API của bạn vào một tệp cấu hình cục bộ. Bạn đã sẵn sàng chạy các lệnh.

Shipyard tự lưu trữ

Để dùng Shipyard tự lưu trữ, hãy trỏ CLI đến API của nó trong ~/.shipyard/config.yaml (hoặc bằng SHIPYARD_API_URL) trước khi đăng nhập:

api_url: https://shipyard.example.internal/api/v1
self_update: false

Sau đó, shipyard login sẽ mở trang đăng nhập của máy chủ đó và mọi lệnh sẽ gọi API đó. Đặt self_update: false nếu bản cài đặt không thể kết nối với GitHub (xem Tắt tính năng tự cập nhật).

Nếu bạn đã đăng nhập vào một Shipyard khác (chẳng hạn như shipyard.build), shipyard login sẽ giữ lại token đó và cho biết bạn đã đăng nhập. Hãy xóa api_token khỏi tệp cấu hình (và bỏ đặt SHIPYARD_API_TOKEN) trước khi đăng nhập vào bản cài đặt tự lưu trữ.

Hoặc đặt token theo cách thủ công

Đặt token API Shipyard làm giá trị của biến môi trường SHIPYARD_API_TOKEN.

Bạn có thể lấy token bằng cách truy cập trang hồ sơ của bạn.

Nếu muốn bật quyền truy cập API cho tổ chức của mình, bạn có thể liên hệ với chúng tôi qua support@shipyard.build. Nếu có câu hỏi nào khác, hãy tham gia cộng đồng Slack của chúng tôi.

shipyard set token

Ngoài ra, bạn có thể dùng tệp cấu hình được lưu tại $HOME/.shipyard/config.yaml theo mặc định. Khi chạy CLI lần đầu, CLI sẽ tạo một tệp cấu hình trống mặc định để bạn chỉnh sửa.

Bạn cũng có thể chỉ định đường dẫn cấu hình không mặc định bằng cách thêm cờ --config {path} vào bất kỳ lệnh nào.

Thêm các giá trị cấu hình vào tệp cấu hình và đảm bảo tệp tuân theo cú pháp YAML. Ví dụ:

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

Các giá trị của biến môi trường sẽ ghi đè các giá trị tương ứng trong tệp cấu hình.

Cách sử dụng cơ bản

Lấy danh sách tất cả tổ chức bạn là thành viên

shipyard get orgs

Đặt tổ chức mặc định toàn cục

shipyard set org {org-name}

Lấy tổ chức hiện được cấu hình

shipyard get org

Liệt kê tất cả môi trường

shipyard get environments

Các cờ khả dụng:

Tên	Mô tả	Kiểu	Giá trị mặc định
branch	Lọc theo tên nhánh	string
deleted	Trả về các môi trường đã xóa	boolean	false
json	In toàn bộ đầu ra JSON	boolean	false
name	Lọc theo tên ứng dụng	string
org-name	Lọc theo tên tổ chức nếu bạn thuộc nhiều tổ chức	string	tổ chức mặc định
page	Số trang được yêu cầu	int	1
page-size	Kích thước trang được yêu cầu	int	20
pull-request-number	Lọc theo số pull request	string
repo-name	Lọc theo tên repo	string

Ví dụ:

• Liệt kê tất cả môi trường đang chạy repo flask-backend trên nhánh main:

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

• Liệt kê tất cả môi trường đã xóa:

shipyard get environments --deleted

Lấy thông tin chi tiết của một môi trường cụ thể theo UUID

shipyard get environment {environment_uuid}

Các cờ khả dụng:

Tên	Mô tả	Kiểu	Giá trị mặc định
json	In toàn bộ đầu ra JSON	boolean	false
org	Tổ chức của môi trường nếu bạn thuộc nhiều tổ chức	string	tổ chức mặc định
bypass-token	Chỉ in token bypass của môi trường, dành cho script	boolean	false

--bypass-token cho phép script sử dụng token mà không cần ai nhập hoặc in token đó:

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

Dừng một môi trường đang chạy

shipyard stop environment {environment_uuid}

Khởi động lại một môi trường đã dừng

shipyard restart environment {environment_uuid}

Hủy bản dựng đang chạy cho một môi trường

shipyard cancel environment {environment_uuid}

Tạo lại bản dựng của một môi trường

shipyard rebuild environment {environment_uuid}

Khôi phục một môi trường đã xóa

shipyard revive environment {environment_uuid}

Triển khai môi trường tách rời

Tạo một môi trường mới, độc lập ("tách rời") bằng cách sao chép bản dựng của một ứng dụng hiện có. Yêu cầu tổ chức của bạn đã bật môi trường tách rời.

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

Ghi đè nhánh theo từng repo và kiểm soát việc môi trường tách rời có tạo lại bản dựng khi có commit mới hay không:

# 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

Xóa môi trường tách rời

Truyền UUID của môi trường hoặc UUID của bất kỳ bản dựng ứng dụng nào thuộc môi trường đó (UUID trong URL của trang chi tiết bản dựng). Chỉ môi trường tách rời mới có thể bị xóa theo cách này; môi trường cơ sở, pull request hoặc từ xa sẽ bị từ chối. Xóa lại một môi trường đã bị xóa vẫn thành công.

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

Lấy tất cả dịch vụ và cổng được mở cho một môi trường

shipyard get services --env {environment_uuid}

Thực thi lệnh trong dịch vụ của môi trường đang chạy

Thực thi bất kỳ lệnh nào cùng các đối số và cờ trong một dịch vụ thuộc môi trường đang chạy. Truyền các đối số của lệnh sau dấu gạch chéo kép. Phiên làm việc chỉ ngăn môi trường bị dừng do không hoạt động khi bạn đang nhập lệnh, tối đa 12 giờ.

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

Chuyển tiếp cổng của dịch vụ trong môi trường đang chạy

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

Một port-forward hoặc logs --follow đang mở sẽ ngăn môi trường bị dừng do không hoạt động trong tối đa 12 giờ.

Lấy nhật ký của dịch vụ trong môi trường đang chạy

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

Truy cập một môi trường

shipyard visit {environment_uuid}

Các cờ khả dụng:

Tên	Mô tả	Kiểu	Giá trị mặc định
follow	Theo dõi đầu ra nhật ký	boolean	false
tail	Số dòng nhật ký gần đây cần hiển thị	int	3000

Làm việc với volume

Liệt kê tất cả volume trong một môi trường

shipyard get volumes --env {environment_uuid}

Liệt kê tất cả ảnh chụp volume trong một môi trường

shipyard get snapshots --env {environment_uuid}

Đặt lại một volume trong môi trường

shipyard reset volume --env {environment_uuid}

Tạo ảnh chụp trong môi trường

shipyard create snapshot --env {environment_uuid}

Tải ảnh chụp volume vào môi trường

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

Tải tệp lên volume trong môi trường

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

Gọi trực tiếp REST API

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

Đường dẫn phải bắt đầu bằng /api/v1 hoặc /api/v2; token và tổ chức của bạn sẽ được tự động thêm vào. bypass_token và thông tin xác thực kubeconfig sẽ được che đi, trừ khi bạn truyền --include-secrets.

Kết nối với telepresence

shipyard telepresence connect --env {environment_uuid}

Từ đó, bạn sẽ có thể giao tiếp trực tiếp với tất cả các pod trong namespace. Bạn có thể cần dùng hostname của namespace để giao tiếp với các dịch vụ; bạn có thể lấy hostname này qua telepresence status trong trường Namespace. Ví dụ, để giao tiếp với redis, bạn sẽ dùng redis.shipyard-app-build-{uuid}

Tạo tệp thực thi từ mã nguồn:

Bạn có thể tạo tệp thực thi bằng cách chạy lệnh sau:

make

Để chạy tệp thực thi mới này:

./shipyard

Bật tính năng tự động hoàn thành

Bash

Tập lệnh này phụ thuộc vào gói bash-completion. Nếu gói này chưa được cài đặt, bạn có thể cài đặt thông qua trình quản lý gói của hệ điều hành. Để tải các mục tự động hoàn thành trong phiên shell hiện tại:

source <(shipyard completion bash)

Để tải các mục tự động hoàn thành trong mỗi phiên mới, hãy thực thi lệnh sau một lần.

Trên Linux:

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

Trên macOS:

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

Zsh

Nếu tính năng tự động hoàn thành lệnh trong shell chưa được bật trong môi trường của bạn, bạn cần bật tính năng này. Bạn có thể thực thi lệnh sau một lần:

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

Để tải các mục tự động hoàn thành trong phiên shell hiện tại:

source <(shipyard completion zsh); compdef _shipyard shipyard

Để tải các mục tự động hoàn thành trong mỗi phiên mới, hãy thực thi lệnh sau một lần.

Trên Linux:

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

Trên macOS:

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

Bạn cần khởi động shell mới để thiết lập này có hiệu lực.

Fish

Để tải các mục tự động hoàn thành trong phiên shell hiện tại:

$ shipyard completion fish | source

Để tải các mục tự động hoàn thành trong mỗi phiên, hãy thực thi lệnh sau một lần:

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

PowerShell

Để tải các mục tự động hoàn thành trong phiên shell hiện tại:

shipyard completion powershell | Out-String | Invoke-Expression

Để tải các mục tự động hoàn thành trong mỗi phiên mới, hãy chạy:

shipyard completion powershell > shipyard.ps1

và nạp tệp này từ hồ sơ PowerShell của bạn.

Sử dụng Shipyard từ trợ lý AI (MCP)

shipyard mcp serve chạy máy chủ Model Context Protocol, cho phép trợ lý như Claude Code, Claude Desktop, Cursor hoặc Codex liệt kê, kiểm tra, dựng lại và cấu hình các môi trường của bạn, đọc nhật ký dịch vụ, quản lý volume và xác minh thay đổi đã đẩy lên trong môi trường tương ứng.

Sau khi đăng nhập CLI, hãy thêm CLI vào Claude Code:

claude mcp add shipyard -- shipyard mcp serve

Sau đó, hãy thử hỏi những câu như:

• "Những môi trường nào đang chạy cho repo web?"
• "Cho tôi xem nhật ký của dịch vụ api trên môi trường của nhánh hiện tại."
• "Tại sao bản dựng mới nhất của môi trường này thất bại?"
• "Đặt FEATURE_FLAGS=beta trên môi trường này và khởi động lại dịch vụ worker."
• "Tôi vừa đẩy thay đổi lên. Hãy xác minh thay đổi trong môi trường tương ứng." (hoặc /mcp__shipyard__verify)

Xem hướng dẫn MCP để biết cách thiết lập trong các ứng dụng khác, cấu hình, danh sách đầy đủ các công cụ, lời nhắc verify và cách khắc phục sự cố.