Shipyard

La CLI Shipyard

Un outil pour gérer les environnements éphémères sur la plateforme Shipyard.

Vous utilisez un assistant IA ? La CLI inclut un serveur MCP : consultez Utiliser Shipyard depuis un assistant IA.

Installation

• Linux et macOS

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

  L’installation se fait dans /usr/local/bin, et utilise sudo uniquement si elle ne peut pas écrire à cet emplacement. Pour installer ailleurs, par exemple dans un répertoire dont vous êtes propriétaire, définissez SHIPYARD_INSTALL_DIR :

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

• Windows Accédez à la page des versions et téléchargez l’exécutable pour Windows.

• Homebrew

  brew tap shipyard/tap
  brew install shipyard
  

Vérifier un téléchargement

Chaque version publie un checksums.txt contenant le SHA-256 de chaque binaire. Le script d’installation vérifie le binaire à l’aide de celui-ci et refuse de l’installer en cas de différence. Pour vérifier un binaire que vous avez téléchargé vous-même :

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

checksums.txt provient de la même version que le binaire ; il détecte donc un téléchargement corrompu ou tronqué, mais pas une version dont les fichiers ont été remplacés. L’attestation ci-dessous vérifie que le binaire a été créé par le workflow de publication de ce dépôt.

Dans les versions postérieures à 1.9.0, chaque binaire possède également une attestation signée de provenance de build, indiquant quel workflow, commit et tag l’ont créé, ainsi qu’une SBOM SPDX (shipyard-<os>-<arch>.sbom.json ; .exe.sbom.json sous Windows) répertoriant les éléments utilisés pour sa création. Vérifiez l’attestation avec la CLI GitHub, en indiquant la version que vous avez téléchargée (ici 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

Conservez --source-ref : sans cela, la vérification réussit pour tout élément signé par une copie du workflow sur n’importe quelle branche, et pas seulement pour le build associé au tag de cette version.

La vérification indique le tag, pas son commit. Les attestations d’une version retirée ne sont pas supprimées ; si une version est publiée à nouveau sous le même tag, ses binaires retirés passent toujours la vérification. Pour épingler également le commit, ajoutez --source-digest <commit SHA> avec le commit vers lequel pointe le tag.

Reconstruire une version

Les versions postérieures à 1.10.0 sont reproductibles : reconstruire le tag de la version avec les mêmes versions de Go et de GoReleaser produit des binaires identiques octet pour octet, quel que soit le répertoire. Les versions sont GO_VERSION et GORELEASER_VERSION dans le .github/workflows/release.yaml de ce tag. Avec cette version de GoReleaser installée et GO_VERSION à la place de 1.26.11 ci-dessous (GOTOOLCHAIN fait utiliser à Go exactement cette version, en la téléchargeant si nécessaire, et GOFLAGS= supprime vos propres options de build) :

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

Le condensat doit correspondre à la même ligne dans le checksums.txt de la version. Si ce n’est pas le cas, vérifiez vos versions de Go et de GoReleaser (GOTOOLCHAIN=go1.26.11 go version, goreleaser --version) avant de suspecter la version. Le workflow de publication vérifie cela sur chaque commit de publication avant de créer la version (scripts/check-reproducible.sh). Les SBOM ne sont pas reproductibles : elles indiquent la date de leur génération. Leur entrée pour le propre module de la CLI affiche la version (devel), car le build omet l’empreinte VCS de Go ; shipyard --version affiche la version de publication.

Mise à niveau

shipyard upgrade

shipyard update fait la même chose. Il installe la dernière version et affiche ses notes de publication. Une installation Homebrew est mise à niveau avec brew upgrade shipyard ; toute autre installation télécharge le binaire de la version, le vérifie à l’aide du checksums.txt de la version, puis remplace le binaire en cours d’exécution. Si ce binaire se trouve dans un répertoire où vous ne pouvez pas écrire, comme /usr/local/bin, exécutez sudo shipyard upgrade.

Ajoutez --prerelease pour inclure les préversions, ou --force pour réinstaller la version actuelle (pour une installation Homebrew, utilisez brew reinstall shipyard à la place).

Mise à niveau depuis la version 1.9.0 ou une version antérieure

Le shipyard update des versions 1.9.0 et antérieures compare les versions comme du texte ; il considère donc 1.10.0 et les versions ultérieures comme plus anciennes que celle que vous avez. Effectuez une mise à niveau une fois en suivant la méthode d’installation utilisée ; shipyard upgrade fonctionnera ensuite :

• Linux et macOS : curl https://www.shipyard.sh/install.sh | bash
• Windows : téléchargez l’exécutable depuis la page des versions
• Homebrew : brew upgrade shipyard

Notifications de mise à jour

Lorsqu’une nouvelle version est disponible, la CLI vous en informe à la fin d’une commande, au maximum une fois par jour :

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

Elle ne pose jamais de question et n’attend jamais de saisie. La vérification s’exécute en arrière-plan pendant l’exécution de votre commande ; si elle n’est pas terminée lorsque la commande se termine, la CLI l’attend pendant une seconde au maximum. Cela ne se produit que lorsqu’elle interroge GitHub, environ une fois par jour, ou lorsqu’elle récupère les notes de publication que vous avez manquées. La première exécution après une mise à niveau effectuée par un autre moyen, comme brew upgrade, affiche ces notes.

Le message est envoyé sur stderr, et uniquement lorsque stderr est un terminal. Il ne s’affiche jamais dans CI, dans les agents de programmation IA qui s’identifient (Claude Code, Codex, l’agent de Cursor, Gemini CLI), ni pour shipyard mcp serve. Pour le désactiver, définissez SHIPYARD_NO_UPDATE_CHECK=1 ou ajoutez update_check: false à ~/.shipyard/config.yaml.

Désactiver la mise à jour automatique

Sur une instance Shipyard auto-hébergée qui ne peut pas accéder à GitHub, la CLI est fournie avec votre version de Shipyard. Désactivez-y la mise à jour automatique avec self_update: false dans ~/.shipyard/config.yaml, ou SHIPYARD_SELF_UPDATE=false. La CLI ne contacte alors jamais GitHub : aucune notification de mise à jour, aucune vérification en arrière-plan depuis shipyard mcp serve, et shipyard upgrade refuse de s’exécuter en indiquant que la mise à jour automatique est désactivée. update_check: false désactive uniquement la notification et la vérification en arrière-plan.

Connexion

Exécutez shipyard login pour initialiser la CLI. Vous serez invité à vous connecter à Shipyard dans le navigateur. La CLI enregistrera ensuite votre jeton API dans un fichier de configuration local. Vous pourrez alors commencer à exécuter des commandes.

Shipyard auto-hébergé

Pour utiliser une instance Shipyard auto-hébergée, indiquez à la CLI son API dans ~/.shipyard/config.yaml (ou avec SHIPYARD_API_URL) avant de vous connecter :

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

shipyard login ouvre alors la page de connexion de cet hôte, et chaque commande appelle cette API. Définissez self_update: false si l’installation ne peut pas accéder à GitHub (voir Désactiver la mise à jour automatique).

Si vous êtes déjà connecté à une autre instance Shipyard (comme shipyard.build), shipyard login conserve ce jeton et indique que vous êtes connecté. Supprimez api_token du fichier de configuration (et annulez la définition de SHIPYARD_API_TOKEN) avant de vous connecter à l’installation auto-hébergée.

Ou définir votre jeton manuellement

Définissez votre jeton API Shipyard comme valeur de la variable d’environnement SHIPYARD_API_TOKEN.

Vous pouvez l’obtenir en accédant à votre page de profil.

Vous pouvez nous contacter à l’adresse support@shipyard.build si vous souhaitez activer l’accès à l’API pour votre organisation. Pour toute autre question, n’hésitez pas à rejoindre notre communauté sur Slack.

shipyard set token

Vous pouvez également utiliser un fichier de configuration stocké par défaut dans $HOME/.shipyard/config.yaml. Lors de la première exécution de la CLI, un fichier de configuration vide par défaut est créé ; vous pouvez ensuite le modifier.

Vous pouvez aussi indiquer un chemin de configuration différent de celui par défaut avec l’option --config {path} ajoutée à n’importe quelle commande.

Ajoutez les valeurs de configuration souhaitées dans votre fichier et vérifiez qu’il respecte la syntaxe YAML. Par exemple :

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

Les valeurs de vos variables d’environnement remplacent les valeurs correspondantes du fichier de configuration.

Utilisation de base

Obtenir toutes les organisations dont vous êtes membre

shipyard get orgs

Définir l’organisation par défaut globale

shipyard set org {org-name}

Obtenir l’organisation actuellement configurée

shipyard get org

Lister tous les environnements

shipyard get environments

Options disponibles :

Nom	Description	Type	Valeur par défaut
branch	Filtrer par nom de branche	string
deleted	Renvoyer les environnements supprimés	boolean	false
json	Afficher la sortie JSON complète	boolean	false
name	Filtrer par nom d’application	string
org-name	Filtrer par nom d’organisation, si vous appartenez à plusieurs organisations	string	votre organisation par défaut
page	Numéro de page demandé	int	1
page-size	Taille de page demandée	int	20
pull-request-number	Filtrer par numéro de pull request	string
repo-name	Filtrer par nom de dépôt	string

Exemples :

• Lister tous les environnements exécutant le dépôt flask-backend sur la branche main :

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

• Lister tous les environnements supprimés :

shipyard get environments --deleted

Obtenir les détails d’un environnement spécifique à partir de son UUID

shipyard get environment {environment_uuid}

Options disponibles :

Nom	Description	Type	Valeur par défaut
json	Afficher la sortie JSON complète	boolean	false
org	Organisation de l’environnement, si vous appartenez à plusieurs organisations	string	votre organisation par défaut
bypass-token	Afficher uniquement le jeton de contournement de l’environnement, pour les scripts	boolean	false

--bypass-token permet à un script d’utiliser le jeton sans que personne ait à le saisir ou à l’afficher :

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

Arrêter un environnement en cours d’exécution

shipyard stop environment {environment_uuid}

Redémarrer un environnement arrêté

shipyard restart environment {environment_uuid}

Annuler un build en cours pour un environnement

shipyard cancel environment {environment_uuid}

Reconstruire un environnement

shipyard rebuild environment {environment_uuid}

Réactiver un environnement supprimé

shipyard revive environment {environment_uuid}

Déployer un environnement détaché

Créez un nouvel environnement indépendant (« détaché ») en clonant un build d’application existant. Les environnements détachés doivent être activés pour votre organisation.

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

Remplacez les branches par dépôt et contrôlez si l’environnement détaché est reconstruit lors de nouveaux commits :

# 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

Supprimer un environnement détaché

Indiquez l’UUID de l’environnement ou l’UUID de l’un de ses builds d’application (celui qui figure dans l’URL de la page de détails du build). Seuls les environnements détachés peuvent être supprimés de cette manière ; une base, une pull request ou un environnement distant sera refusé. La suppression d’un environnement déjà supprimé réussit également.

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

Obtenir tous les services et les ports exposés d’un environnement

shipyard get services --env {environment_uuid}

Ouvrir une session dans le service d’un environnement en cours d’exécution

Exécutez n’importe quelle commande avec les arguments et options de votre choix dans un service d’un environnement en cours d’exécution. Passez les arguments de commande après une double barre oblique. La session empêche l’arrêt de l’environnement pour cause d’inactivité uniquement pendant que vous y saisissez du texte, pendant 12 heures maximum.

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

Rediriger un port du service d’un environnement en cours d’exécution

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

Un port-forward ou un logs --follow ouvert empêche l’arrêt de l’environnement pour cause d’inactivité pendant 12 heures maximum.

Obtenir les journaux du service d’un environnement en cours d’exécution

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

Accéder à un environnement

shipyard visit {environment_uuid}

Options disponibles :

Nom	Description	Type	Valeur par défaut
follow	Suivre la sortie des journaux	boolean	false
tail	Nombre de lignes de journal récentes à afficher	int	3000

Utiliser les volumes

Lister tous les volumes d’un environnement

shipyard get volumes --env {environment_uuid}

Lister tous les instantanés de volume d’un environnement

shipyard get snapshots --env {environment_uuid}

Réinitialiser un volume dans un environnement

shipyard reset volume --env {environment_uuid}

Créer un instantané dans un environnement

shipyard create snapshot --env {environment_uuid}

Charger un instantané de volume dans un environnement

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

Téléverser un fichier vers un volume dans un environnement

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

Appeler directement l’API REST

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

Les chemins doivent commencer par /api/v1 ou /api/v2 ; votre jeton et votre organisation sont ajoutés automatiquement. bypass_token et les identifiants kubeconfig sont masqués, sauf si vous passez --include-secrets.

Se connecter à Telepresence

shipyard telepresence connect --env {environment_uuid}

À partir de là, vous pourrez communiquer directement avec tous les pods de l’espace de noms. Vous devrez peut-être utiliser le nom d’hôte de l’espace de noms pour communiquer avec les services. Vous pouvez l’obtenir via telepresence status dans le champ Namespace. Par exemple, pour communiquer avec redis, vous utiliserez redis.shipyard-app-build-{uuid}

Créer un exécutable à partir du code :

Vous pouvez créer un exécutable en exécutant la commande suivante :

make

Pour exécuter ce nouvel exécutable :

./shipyard

Activer la complétion automatique

Bash

Ce script dépend du paquet bash-completion. S’il n’est pas déjà installé, vous pouvez l’installer à l’aide du gestionnaire de paquets de votre système d’exploitation. Pour charger les complétions dans votre session shell actuelle :

source <(shipyard completion bash)

Pour charger les complétions à chaque nouvelle session, exécutez la commande suivante une seule fois.

Sous Linux :

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

Sous macOS :

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

Zsh

Si la complétion du shell n’est pas déjà activée dans votre environnement, vous devrez l’activer. Vous pouvez exécuter la commande suivante une seule fois :

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

Pour charger les complétions dans votre session shell actuelle :

source <(shipyard completion zsh); compdef _shipyard shipyard

Pour charger les complétions à chaque nouvelle session, exécutez la commande suivante une seule fois.

Sous Linux :

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

Sous macOS :

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

Vous devrez démarrer un nouveau shell pour que cette configuration prenne effet.

Fish

Pour charger les complétions dans votre session shell actuelle :

$ shipyard completion fish | source

Pour charger les complétions à chaque session, exécutez la commande suivante une seule fois :

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

PowerShell

Pour charger les complétions dans votre session shell actuelle :

shipyard completion powershell | Out-String | Invoke-Expression

Pour charger les complétions à chaque nouvelle session, exécutez :

shipyard completion powershell > shipyard.ps1

et sourcez ce fichier depuis votre profil PowerShell.

Utiliser Shipyard depuis un assistant IA (MCP)

shipyard mcp serve exécute un serveur Model Context Protocol, afin qu’un assistant tel que Claude Code, Claude Desktop, Cursor ou Codex puisse répertorier, inspecter, reconstruire et configurer vos environnements, lire les journaux des services, gérer les volumes et vérifier une modification envoyée par push dans son environnement.

Une fois connecté à la CLI, ajoutez-la à Claude Code :

claude mcp add shipyard -- shipyard mcp serve

Vous pouvez ensuite poser des questions telles que :

• « Quels environnements sont en cours d’exécution pour le dépôt web ? »
• « Affiche les journaux du service api dans l’environnement de ma branche. »
• « Pourquoi la dernière compilation de cet environnement a-t-elle échoué ? »
• « Définis FEATURE_FLAGS=beta sur cet environnement et redémarre le service worker. »
• « Je viens d’envoyer une modification. Vérifie-la dans son environnement. » (ou /mcp__shipyard__verify)

Consultez le guide MCP pour découvrir comment le configurer dans d’autres clients, les options de configuration, la liste complète des outils, le prompt verify et les conseils de dépannage.