Shipyard

Die Shipyard CLI

Ein Tool zur Verwaltung von Ephemeral Environments auf der Shipyard-Plattform.

Verwendest du einen KI-Assistenten? Die CLI enthält einen MCP-Server: siehe Shipyard über einen KI-Assistenten verwenden.

Installation

• Linux und macOS

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

  Die Installation erfolgt unter /usr/local/bin; nur wenn dort nicht geschrieben werden kann, wird sudo verwendet. Um die Installation an einem anderen Ort vorzunehmen, beispielsweise in einem Verzeichnis, das dir gehört, setze SHIPYARD_INSTALL_DIR:

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

• Windows Rufe die Releases-Seite auf und lade die ausführbare Datei für Windows herunter.

• Homebrew

  brew tap shipyard/tap
  brew install shipyard
  

Einen Download überprüfen

Bei jedem Release wird eine checksums.txt mit den SHA-256-Prüfsummen aller Binärdateien veröffentlicht. Das Installationsskript überprüft die Binärdatei anhand dieser Prüfsumme und verweigert die Installation, wenn sie nicht übereinstimmt. So überprüfst du eine selbst heruntergeladene Binärdatei:

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

checksums.txt stammt aus demselben Release wie die Binärdatei. Damit werden beschädigte oder unvollständige Downloads erkannt, nicht jedoch ein Release, dessen Dateien ersetzt wurden. Die folgende Attestierung überprüft, ob die Binärdatei vom Release-Workflow dieses Repos erstellt wurde.

Bei Releases nach 1.9.0 verfügt jede Binärdatei außerdem über eine signierte Build-Provenance-Attestierung, aus der hervorgeht, welcher Workflow-Lauf, Commit und Tag sie erstellt hat, sowie über eine SPDX-SBOM (shipyard-<os>-<arch>.sbom.json; unter Windows .exe.sbom.json), die auflistet, woraus sie erstellt wurde. Überprüfe die Attestierung mit der GitHub CLI und gib dabei das heruntergeladene Release an (hier 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

Behalte --source-ref bei: Ohne diese Angabe ist die Prüfung für alles erfolgreich, was eine Kopie des Workflows auf einem beliebigen Branch signiert hat, nicht nur für den Tag-Build dieses Releases.

Bei der Prüfung wird der Tag angegeben, nicht dessen Commit. Die Attestierungen eines zurückgezogenen Releases werden nicht gelöscht. Wird also jemals erneut ein Release unter demselben Tag veröffentlicht, bestehen auch die zurückgezogenen Binärdateien die Prüfung. Um zusätzlich den Commit festzulegen, füge --source-digest <commit SHA> mit dem Commit hinzu, auf den der Tag verweist.

Ein Release neu erstellen

Releases nach 1.10.0 sind reproduzierbar: Wenn du den Release-Tag mit denselben Go- und GoReleaser-Versionen erneut erstellst, erhältst du in jedem Verzeichnis byte-identische Binärdateien. Die Versionen sind GO_VERSION und GORELEASER_VERSION in der .github/workflows/release.yaml dieses Tags. Wenn GoReleaser installiert ist und du unten 1.26.11 durch GO_VERSION ersetzt (GOTOOLCHAIN sorgt dafür, dass Go genau diese Version verwendet und sie bei Bedarf herunterlädt; GOFLAGS= entfernt alle eigenen Build-Flags):

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

Die Prüfsumme sollte mit derselben Zeile in der checksums.txt des Releases übereinstimmen. Falls nicht, überprüfe deine Go- und GoReleaser-Versionen (GOTOOLCHAIN=go1.26.11 go version, goreleaser --version), bevor du das Release verdächtigst. Der Release-Workflow überprüft dies bei jedem Release-Commit, bevor er das Release erstellt (scripts/check-reproducible.sh). SBOMs sind nicht reproduzierbar: Sie enthalten den Zeitpunkt ihrer Erstellung. Der Eintrag für das eigene Modul der CLI zeigt die Version (devel), da beim Build Go's VCS-Stempel weggelassen wird; shipyard --version gibt die Release-Version aus.

Aktualisieren

shipyard upgrade

shipyard update erledigt dasselbe. Es installiert das neueste Release und zeigt dessen Versionshinweise an. Eine Homebrew-Installation wird mit brew upgrade shipyard aktualisiert; bei jeder anderen Installation wird die Release-Binärdatei heruntergeladen, anhand der checksums.txt des Releases überprüft und ersetzt die laufende Binärdatei. Wenn sich diese Binärdatei in einem Verzeichnis befindet, in das du nicht schreiben kannst, beispielsweise /usr/local/bin, führe sudo shipyard upgrade aus.

Füge --prerelease hinzu, um Vorabversionen einzubeziehen, oder --force, um die aktuelle Version erneut zu installieren (bei einer Homebrew-Installation verwende stattdessen brew reinstall shipyard).

Aktualisieren von Version 1.9.0 oder älter

shipyard update in Version 1.9.0 und älter vergleicht Versionen als Text. Daher werden Version 1.10.0 und spätere Versionen als älter als deine installierte Version gemeldet. Aktualisiere einmal auf die für deine Installation passende Weise; danach funktioniert shipyard upgrade:

• Linux und macOS: curl https://www.shipyard.sh/install.sh | bash
• Windows: Lade die ausführbare Datei von der Releases-Seite herunter
• Homebrew: brew upgrade shipyard

Update-Benachrichtigungen

Wenn ein neues Release verfügbar ist, informiert dich die CLI nach Abschluss eines Befehls, höchstens einmal pro Tag:

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

Sie fragt nie nach etwas und wartet nie auf Eingaben. Die Prüfung läuft im Hintergrund, während dein Befehl ausgeführt wird. Wenn sie beim Abschluss des Befehls noch nicht fertig ist, wartet die CLI höchstens eine Sekunde darauf. Das passiert nur, wenn GitHub abgefragt wird – etwa einmal pro Tag oder um verpasste Versionshinweise abzurufen. Beim ersten Start nach einem anderweitig durchgeführten Upgrade, beispielsweise mit brew upgrade, werden diese Hinweise angezeigt.

Die Meldung wird auf stderr ausgegeben und nur dann, wenn stderr ein Terminal ist. Sie wird nie in CI, in KI-Coding-Agenten, die sich zu erkennen geben (Claude Code, Codex, Cursor's agent, Gemini CLI), oder für shipyard mcp serve angezeigt. Um sie zu deaktivieren, setze SHIPYARD_NO_UPDATE_CHECK=1 oder füge update_check: false zu ~/.shipyard/config.yaml hinzu.

Selbstaktualisierung deaktivieren

Bei einem selbst gehosteten Shipyard, das GitHub nicht erreichen kann, wird die CLI zusammen mit deinem Shipyard-Release bereitgestellt. Deaktiviere dort die Selbstaktualisierung mit self_update: false in ~/.shipyard/config.yaml oder mit SHIPYARD_SELF_UPDATE=false. Die CLI kontaktiert GitHub dann nie: Es gibt keine Update-Benachrichtigung, keine Hintergrundprüfung durch shipyard mcp serve, und shipyard upgrade wird mit einer Meldung abgelehnt, dass die Selbstaktualisierung deaktiviert ist. update_check: false deaktiviert nur die Benachrichtigung und die Hintergrundprüfung.

Anmelden

Führe shipyard login aus, um die CLI zu initialisieren. Du wirst aufgefordert, dich im Browser bei Shipyard anzumelden. Anschließend speichert die CLI dein API-Token in einer lokalen Konfiguration. Danach kannst du mit der Ausführung von Befehlen beginnen.

Selbst gehostetes Shipyard

Um ein selbst gehostetes Shipyard zu verwenden, richte die CLI vor der Anmeldung in ~/.shipyard/config.yaml auf dessen API aus (oder verwende SHIPYARD_API_URL):

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

shipyard login öffnet dann die Anmeldeseite dieses Hosts, und jeder Befehl ruft diese API auf. Setze self_update: false, wenn die Installation GitHub nicht erreichen kann (siehe Selbstaktualisierung deaktivieren).

Wenn du bereits bei einem anderen Shipyard (beispielsweise shipyard.build) angemeldet bist, behält shipyard login dieses Token bei und meldet, dass du angemeldet bist. Entferne api_token aus der Konfigurationsdatei (und hebe die Setzung von SHIPYARD_API_TOKEN auf), bevor du dich bei der selbst gehosteten Installation anmeldest.

Oder Token manuell festlegen

Lege dein Shipyard-API-Token als Wert der Umgebungsvariable SHIPYARD_API_TOKEN fest.

Du findest es auf deiner Profilseite.

Wenn du den API-Zugriff für deine Organisation aktivieren möchtest, kontaktiere uns unter support@shipyard.build. Bei weiteren Fragen kannst du unserer Community auf Slack beitreten.

shipyard set token

Alternativ kannst du eine Konfigurationsdatei verwenden, die standardmäßig unter $HOME/.shipyard/config.yaml gespeichert wird. Beim ersten Ausführen der CLI wird eine leere Standardkonfiguration erstellt, die du anschließend bearbeiten kannst.

Du kannst auch mit dem Flag --config {path}, das du einem beliebigen Befehl hinzufügst, einen abweichenden Konfigurationspfad angeben.

Füge beliebige Konfigurationswerte in deine Konfiguration ein und achte darauf, dass die Datei der YAML-Syntax entspricht. Zum Beispiel:

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

Die Werte deiner Umgebungsvariablen überschreiben die entsprechenden Werte in der Konfiguration.

Grundlegende Verwendung

Alle Organisationen abrufen, in denen du Mitglied bist

shipyard get orgs

Globale Standardorganisation festlegen

shipyard set org {org-name}

Aktuell konfigurierte Organisation abrufen

shipyard get org

Alle Umgebungen auflisten

shipyard get environments

Verfügbare Flags:

Name	Beschreibung	Typ	Standardwert
branch	Nach Branch-Namen filtern	string
deleted	Gelöschte Umgebungen zurückgeben	boolean	false
json	Die vollständige JSON-Ausgabe ausgeben	boolean	false
name	Nach Anwendungsnamen filtern	string
org-name	Nach Organisationsnamen filtern, wenn du mehreren Organisationen angehörst	string	deine Standardorganisation
page	Angeforderte Seitennummer	int	1
page-size	Angeforderte Seitengröße	int	20
pull-request-number	Nach Pull-Request-Nummer filtern	string
repo-name	Nach Repository-Namen filtern	string

Beispiele:

• Alle Umgebungen auflisten, in denen das Repository flask-backend auf dem Branch main ausgeführt wird:

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

• Alle gelöschten Umgebungen auflisten:

shipyard get environments --deleted

Details zu einer bestimmten Umgebung anhand ihrer UUID abrufen

shipyard get environment {environment_uuid}

Verfügbare Flags:

Name	Beschreibung	Typ	Standardwert
json	Die vollständige JSON-Ausgabe ausgeben	boolean	false
org	Organisation der Umgebung, wenn du mehreren Organisationen angehörst	string	deine Standardorganisation
bypass-token	Nur das Bypass-Token der Umgebung ausgeben, für Skripte	boolean	false

Mit --bypass-token kann ein Skript das Token verwenden, ohne dass jemand es eingeben oder ausgeben muss:

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

Laufende Umgebung anhalten

shipyard stop environment {environment_uuid}

Angehaltene Umgebung neu starten

shipyard restart environment {environment_uuid}

Laufenden Build für eine Umgebung abbrechen

shipyard cancel environment {environment_uuid}

Umgebung neu erstellen

shipyard rebuild environment {environment_uuid}

Gelöschte Umgebung wiederherstellen

shipyard revive environment {environment_uuid}

Eine unabhängige Umgebung bereitstellen

Erstelle eine neue, unabhängige („detached“) Umgebung, indem du einen vorhandenen Anwendungs-Build klonst. Für deine Organisation müssen unabhängige Umgebungen aktiviert sein.

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

Überschreibe Branches pro Repository und lege fest, ob die unabhängige Umgebung bei neuen Commits neu erstellt wird:

# 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

Eine unabhängige Umgebung löschen

Übergib die UUID der Umgebung oder die UUID eines ihrer Anwendungs-Builds (die in der URL der Build-Detailseite). Auf diese Weise können nur unabhängige Umgebungen gelöscht werden; eine Basis-, Pull-Request- oder Remote-Umgebung wird abgelehnt. Das erneute Löschen einer bereits gelöschten Umgebung ist ebenfalls erfolgreich.

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

Alle Services und freigegebenen Ports einer Umgebung abrufen

shipyard get services --env {environment_uuid}

In den Service einer laufenden Umgebung wechseln

Führe beliebige Befehle mit beliebigen Argumenten und Flags in einem Service einer laufenden Umgebung aus. Übergib alle Befehlsargumente nach einem doppelten Schrägstrich. Die Sitzung verhindert, dass die Umgebung wegen Inaktivität angehalten wird, solange du darin tippst, bis zu 12 Stunden lang.

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

Port eines Services einer laufenden Umgebung weiterleiten

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

Ein offenes port-forward oder logs --follow verhindert bis zu 12 Stunden lang, dass die Umgebung wegen Inaktivität angehalten wird.

Logs eines Services einer laufenden Umgebung abrufen

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

Eine Umgebung aufrufen

shipyard visit {environment_uuid}

Verfügbare Flags:

Name	Beschreibung	Typ	Standardwert
follow	Logausgabe fortlaufend anzeigen	boolean	false
tail	Anzahl der letzten anzuzeigenden Logzeilen	int	3000

Mit Volumes arbeiten

Alle Volumes in einer Umgebung auflisten

shipyard get volumes --env {environment_uuid}

Alle Volume-Snapshots in einer Umgebung auflisten

shipyard get snapshots --env {environment_uuid}

Ein Volume in einer Umgebung zurücksetzen

shipyard reset volume --env {environment_uuid}

Einen Snapshot in einer Umgebung erstellen

shipyard create snapshot --env {environment_uuid}

Einen Volume-Snapshot in eine Umgebung laden

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

Eine Datei in ein Volume einer Umgebung hochladen

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

Die REST-API direkt aufrufen

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

Pfade müssen mit /api/v1 oder /api/v2 beginnen; dein Token und deine Organisation werden automatisch hinzugefügt. bypass_token und kubeconfig-Anmeldedaten werden unkenntlich gemacht, sofern du nicht --include-secrets übergibst.

Mit Telepresence verbinden

shipyard telepresence connect --env {environment_uuid}

Von dort aus kannst du direkt mit allen Pods im Namespace kommunizieren. Möglicherweise musst du den Hostnamen des Namespace verwenden, um mit Services zu kommunizieren. Du findest ihn unter telepresence status im Feld Namespace. Um beispielsweise mit redis zu kommunizieren, würdest du redis.shipyard-app-build-{uuid} verwenden.

Aus dem Code eine ausführbare Datei erstellen:

Du kannst eine ausführbare Datei erstellen, indem du den folgenden Befehl ausführst:

make

So führst du diese neue ausführbare Datei aus:

./shipyard

Autovervollständigung aktivieren

Bash

Dieses Skript benötigt das Paket bash-completion. Falls es noch nicht installiert ist, kannst du es über den Paketmanager deines Betriebssystems installieren. So lädst du die Vervollständigungen in deiner aktuellen Shell-Sitzung:

source <(shipyard completion bash)

So lädst du die Vervollständigungen bei jeder neuen Sitzung, führe den folgenden Befehl einmal aus.

Unter Linux:

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

Unter macOS:

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

Zsh

Falls die Shell-Vervollständigung in deiner Umgebung noch nicht aktiviert ist, musst du sie aktivieren. Führe dazu einmal den folgenden Befehl aus:

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

So lädst du die Vervollständigungen in deiner aktuellen Shell-Sitzung:

source <(shipyard completion zsh); compdef _shipyard shipyard

So lädst du die Vervollständigungen bei jeder neuen Sitzung, führe den folgenden Befehl einmal aus.

Unter Linux:

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

Unter macOS:

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

Damit diese Einrichtung wirksam wird, musst du eine neue Shell starten.

Fish

So lädst du die Vervollständigungen in deiner aktuellen Shell-Sitzung:

$ shipyard completion fish | source

So lädst du die Vervollständigungen bei jeder Sitzung, führe den folgenden Befehl einmal aus:

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

PowerShell

So lädst du die Vervollständigungen in deiner aktuellen Shell-Sitzung:

shipyard completion powershell | Out-String | Invoke-Expression

So lädst du die Vervollständigungen bei jeder neuen Sitzung, führe Folgendes aus:

shipyard completion powershell > shipyard.ps1

und binde diese Datei in dein PowerShell-Profil ein.

Shipyard mit einem KI-Assistenten verwenden (MCP)

shipyard mcp serve führt einen Server für das Model Context Protocol aus, sodass ein Assistent wie Claude Code, Claude Desktop, Cursor oder Codex deine Umgebungen auflisten, untersuchen, neu erstellen und konfigurieren, Service-Logs lesen, Volumes verwalten und eine gepushte Änderung anhand ihrer Umgebung überprüfen kann.

Wenn du in der CLI angemeldet bist, füge sie zu Claude Code hinzu:

claude mcp add shipyard -- shipyard mcp serve

Stelle anschließend Fragen wie:

• „Welche Umgebungen laufen für das Repository web?“
• „Zeig mir die Logs des Services api in der Umgebung meines Branches.“
• „Warum ist der letzte Build dieser Umgebung fehlgeschlagen?“
• „Setze FEATURE_FLAGS=beta in dieser Umgebung und starte den Service worker neu.“
• „Ich habe gerade einen Push durchgeführt. Überprüfe die Änderung anhand ihrer Umgebung.“ (oder /mcp__shipyard__verify)

Im MCP-Leitfaden findest du Informationen zur Einrichtung in anderen Clients, zur Konfiguration, zur vollständigen Tool-Liste, zum Prompt verify und zur Fehlerbehebung.