Shipyard
公式Shipyard CLIは、エージェントがShipyard環境を直接管理するためのMCPサーバーを提供します。ログの取得、ブランチの比較、テストの実行、環境の停止/開始が可能です。
Shipyard MCPで何ができますか?
- 環境の一覧表示 — リポジトリ、ブランチ、プルリクエスト番号、または名前で絞り込んで、実行中の環境を確認します。
- 環境の詳細確認 — UUIDを指定して、サービスや公開ポートを含む特定の環境の詳細を取得します。
- サービスログの確認 — 実行中の環境にあるサービスのログを表示します。出力を追跡することもできます。
- 環境のライフサイクル管理 — UUIDを指定して、環境の停止、再起動、キャンセル、再構築、または復旧を行います。
- 環境変数の設定 — 環境に環境変数を設定し、サービスを再起動して反映します。
- プッシュした変更の検証 —
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
ダウンロードの検証
各リリースでは、各バイナリの 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)も付属します。ダウンロードしたリリースを指定して(ここでは v1.10.0)、GitHub CLIでアテステーションを検証します。
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 はコマンドの終了後に通知します。通知は1日に最大1回です。
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 に問い合わせるとき(通常は1日に1回、または見逃したリリースノートを取得するとき)に限って発生します。brew upgrade など、別の方法でアップグレードした後の初回実行時には、リリースノートが表示されます。
メッセージは stderr に出力され、stderr がターミナルの場合に限り表示されます。CI、自己申告する AI コーディングエージェント(Claude Code、Codex、Cursor の 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 login を実行して CLI を初期化します。ブラウザーで Shipyard にログインするよう求められます。その後、CLI は API トークンをローカル設定に保存します。これでコマンドを実行する準備が整います。
セルフホスト型 Shipyard
セルフホスト型 Shipyard を使用するには、ログイン前に ~/.shipyard/config.yaml(または SHIPYARD_API_URL)で CLI の接続先 API を指定します。
api_url: https://shipyard.example.internal/api/v1
self_update: false
shipyard login を実行すると、そのホストのログインページが開き、すべてのコマンドがその API を呼び出します。インストール環境から GitHub に接続できない場合は self_update: false を設定してください(自動更新を無効にするを参照)。
すでに別の Shipyard(shipyard.build など)にログインしている場合、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 |
例:
- ブランチ
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 | スクリプト用に環境のバイパストークンのみを表示する | 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}
実行中の環境のサービスに 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}
そこから、名前空間内のすべての Pod と直接通信できるようになります。サービスとの通信には名前空間のホスト名を使う必要がある場合があります。これは 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 プロファイルから読み込みます。
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 を参照してください。