Shipyard

CLI Shipyard

Инструмент для управления эфемерными средами на платформе Shipyard.

Используете ИИ-ассистента? В CLI есть MCP-сервер: см. Использование 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 в любом каталоге даёт побайтно идентичные бинарные файлы. Версии указаны как GO_VERSION и GORELEASER_VERSION в .github/workflows/release.yaml этого тега. Установив эту версию GoReleaser и подставив GO_VERSION вместо 1.26.11 ниже (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), поскольку при сборке не сохраняется VCS-метка Go; 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 или более ранней

Команда shipyard update в версии 1.9.0 и более ранних сравнивает версии как текст, поэтому считает версии 1.10.0 и новее более старыми, чем установленная у вас. Один раз обновитесь тем же способом, которым устанавливали CLI, и после этого 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 никогда ничего не спрашивает и не ждёт ввода. Проверка выполняется в фоновом режиме, пока работает команда; если к её завершению проверка не закончилась, CLI ждёт не более секунды. Это происходит только при обращении к GitHub — примерно раз в день или при загрузке пропущенных примечаний к релизу. При первом запуске после обновления другим способом, например с помощью brew upgrade, отображаются эти примечания.

Сообщение выводится в stderr и только если stderr подключён к терминалу. Оно никогда не отображается в CI, внутри ИИ-агентов для программирования, которые сообщают о себе (Claude Code, Codex, агент Cursor, Gemini CLI), или для shipyard mcp serve. Чтобы отключить уведомления, задайте SHIPYARD_NO_UPDATE_CHECK=1 или добавьте update_check: false в ~/.shipyard/config.yaml.

Отключение самостоятельного обновления

В самостоятельно размещённой версии Shipyard, у которой нет доступа к GitHub, CLI поставляется вместе с релизом Shipyard. Отключите там самостоятельное обновление, задав self_update: false в ~/.shipyard/config.yaml или SHIPYARD_SELF_UPDATE=false. После этого CLI никогда не обращается к GitHub: не показывает уведомления об обновлениях, не выполняет фоновую проверку из shipyard mcp serve, а команда shipyard upgrade отказывает с сообщением о том, что самостоятельное обновление отключено. update_check: false отключает только уведомления и фоновую проверку.

Вход в систему

Выполните shipyard login, чтобы инициализировать CLI. Вам будет предложено войти в Shipyard через браузер. Затем CLI сохранит ваш API-токен в локальной конфигурации. После этого можно выполнять команды.

Самостоятельно размещённая версия Shipyard

Чтобы использовать самостоятельно размещённую версию Shipyard, перед входом укажите API-адрес CLI в ~/.shipyard/config.yaml (или с помощью SHIPYARD_API_URL):

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

Затем shipyard login откроет страницу входа этого хоста, и все команды будут обращаться к этому API. Задайте self_update: false, если установка не может подключиться к GitHub (см. Отключение самостоятельного обновления).

Если вы уже вошли в другую версию Shipyard (например, shipyard.build), команда shipyard login сохранит этот токен и сообщит, что вы вошли в систему. Перед входом в самостоятельно размещённую версию удалите api_token из файла конфигурации (и сбросьте SHIPYARD_API_TOKEN).

Или задайте токен вручную

Задайте API-токен Shipyard в качестве значения переменной окружения 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	Вывести только токен обхода среды для скриптов	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 страницы сведений о сборке). Таким способом можно удалить только автономные среды; для базовой среды, среды pull request или удалённой среды команда завершится отказом. Повторное удаление уже удалённой среды также завершается успешно.

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; токен и организацию CLI добавит автоматически. Учётные данные bypass_token и kubeconfig скрываются, если не передать --include-secrets.

Подключиться к telepresence

shipyard telepresence connect --env {environment_uuid}

Отсюда вы сможете напрямую взаимодействовать со всеми подами в пространстве имён. Возможно, для взаимодействия с сервисами потребуется использовать имя хоста пространства имён. Его можно получить с помощью telepresence status в поле Namespace. Например, для взаимодействия с redis используйте redis.shipyard-app-build-{uuid}

Сборка исполняемого файла из кода:

Создать исполняемый файл можно, выполнив следующую команду:

make

Чтобы запустить этот новый исполняемый файл:

./shipyard

Включение автодополнения

Bash

Этот скрипт зависит от пакета bash-completion. Если он ещё не установлен, его можно установить с помощью менеджера пакетов вашей ОС. Чтобы загрузить автодополнение в текущем сеансе оболочки:

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.

Использование 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.