Shipyard

공식

Shipyard CLI는 에이전트가 Shipyard 환경을 직접 관리할 수 있도록 MCP 서버를 제공합니다: 로그 가져오기, 브랜치 비교, 테스트 실행, 환경 중지/시작 등을 수행합니다.

GitHub

Shipyard MCP(으)로 무엇을 할 수 있나요?

환경 목록 조회 — 저장소, 브랜치, 풀 리퀘스트 번호 또는 이름으로 필터링하여 실행 중인 환경을 확인합니다.
환경 검사 — UUID로 특정 환경의 세부 정보와 서비스 및 노출된 포트를 확인합니다.
서비스 로그 읽기 — 실행 중인 환경의 서비스 로그를 표시하며, 선택적으로 출력을 계속 확인할 수 있습니다.
환경 수명 주기 관리 — UUID로 환경을 중지, 재시작, 취소, 재빌드 또는 복구합니다.
환경 변수 구성 — 환경에 환경 변수를 설정하고 적용을 위해 서비스를 재시작합니다.
푸시된 변경 사항 확인 — verify 프롬프트를 사용하여 푸시된 변경 사항을 해당 환경에서 확인합니다.

문서

Shipyard CLI

Shipyard 플랫폼에서 Ephemeral Environments를 관리하는 도구입니다.

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

다운로드 확인

각 릴리스에는 각 바이너리의 SHA-256이 포함된 checksums.txt이 게시됩니다. 설치 스크립트는 바이너리를 해당 값과 비교하고, 일치하지 않으면 설치를 거부합니다. 직접 다운로드한 바이너리를 확인하려면 다음을 실행하세요.

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 자체 모듈의 항목에는 빌드에서 Go의 VCS 스탬프를 제외하기 때문에 버전이 (devel)로 표시됩니다. 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는 어떤 것도 묻거나 입력을 기다리지 않습니다. 명령이 실행되는 동안 백그라운드에서 확인하며, 명령이 끝날 때까지 확인이 완료되지 않으면 최대 1초 동안 기다립니다. GitHub에 요청할 때, 즉 하루에 한 번 정도 또는 놓친 릴리스 노트를 가져올 때만 이런 일이 발생합니다. brew upgrade처럼 다른 방법으로 업그레이드한 후 처음 실행하면 해당 노트가 표시됩니다.

메시지는 stderr로 출력되며 stderr가 터미널인 경우에만 표시됩니다. CI, 자신을 식별하는 AI 코딩 에이전트(Claude Code, Codex, Cursor's agent, Gemini CLI) 내부 또는 shipyard mcp serve에서는 표시되지 않습니다. 끄려면 SHIPYARD_NO_UPDATE_CHECK=1을 설정하거나 ~/.shipyard/config.yaml에 update_check: false을 추가하세요.

자동 업데이트 끄기

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.build와 같은 다른 Shipyard에 이미 로그인한 경우 shipyard login는 해당 토큰을 유지하고 로그인되어 있다고 표시합니다. 자체 호스팅 설치에 로그인하기 전에 설정 파일에서 api_token을 제거하고 SHIPYARD_API_TOKEN을 설정 해제하세요.

토큰 직접 설정하기

Shipyard API 토큰을 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	풀 리퀘스트 번호로 필터링	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	스크립트용으로 환경의 우회 토큰만 출력	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에 있는 UUID)를 전달하세요. 분리된 환경만 이 방법으로 삭제할 수 있습니다. 기본 환경, 풀 리퀘스트 환경 또는 원격 환경은 거부됩니다. 이미 삭제된 환경을 다시 삭제해도 성공합니다.

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

환경의 모든 서비스와 노출된 포트 가져오기

shipyard get services --env {environment_uuid}

실행 중인 환경의 서비스에 exec로 접속하기

실행 중인 환경의 지정된 서비스에서 인수와 플래그를 포함한 모든 명령을 실행합니다. 명령 인수는 이중 슬래시 뒤에 전달하세요. 세션은 입력하는 동안에만 환경이 유휴 상태로 중지되지 않도록 하며, 최대 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}

그곳에서 네임스페이스의 모든 파드와 직접 통신할 수 있습니다. 서비스와 통신하려면 네임스페이스 호스트 이름을 사용해야 할 수도 있습니다. 이 이름은 Namespace 필드의 telepresence status에서 확인할 수 있습니다. 예를 들어 redis와 통신하려면 redis.shipyard-app-build-{uuid}를 사용하면 됩니다.

코드에서 실행 파일 빌드:

다음 명령을 실행하여 실행 파일을 만들 수 있습니다.

make

새 실행 파일을 실행하려면:

./shipyard

자동 완성 사용 설정

Bash

이 스크립트는 bash-completion 패키지에 의존합니다. 아직 설치되어 있지 않다면 OS의 패키지 관리자를 통해 설치할 수 있습니다. 현재 셸 세션에서 자동 완성을 불러오려면:

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

환경에서 셸 자동 완성이 아직 사용 설정되어 있지 않다면 사용 설정해야 합니다. 다음 명령을 한 번 실행하면 됩니다.

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

현재 셸 세션에서 자동 완성을 불러오려면:

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

이 설정을 적용하려면 새 셸을 시작해야 합니다.

Fish

현재 셸 세션에서 자동 완성을 불러오려면:

$ shipyard completion fish | source

각 세션에서 자동 완성을 불러오려면 다음 명령을 한 번 실행하세요.

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

PowerShell

현재 셸 세션에서 자동 완성을 불러오려면:

shipyard completion powershell | Out-String | Invoke-Expression

새 세션을 시작할 때마다 자동 완성을 불러오려면 다음을 실행하세요.

shipyard completion powershell > shipyard.ps1

그리고 PowerShell 프로필에서 이 파일을 source하세요.

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)

다른 클라이언트에서 설정하는 방법, 구성, 전체 도구 목록, verify 프롬프트 및 문제 해결 방법은 **MCP guide**를 참조하세요.