Shipyard

La CLI de Shipyard

Una herramienta para gestionar entornos efímeros en la plataforma Shipyard.

¿Usas un asistente de IA? La CLI incluye un servidor MCP: consulta Usar Shipyard desde un asistente de IA.

Instalación

• Linux y macOS

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

  Se instala en /usr/local/bin, y usa sudo solo si no puede escribir allí. Para instalarla en otro lugar, como un directorio de tu propiedad, establece SHIPYARD_INSTALL_DIR:

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

• Windows Ve a la página de versiones y descarga el ejecutable para Windows.

• Homebrew

  brew tap shipyard/tap
  brew install shipyard
  

Verificar una descarga

Cada versión publica un checksums.txt con el SHA-256 de cada binario. El script de instalación comprueba el binario con ese valor y se niega a instalarlo si no coincide. Para comprobar un binario que hayas descargado por tu cuenta:

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

checksums.txt proviene de la misma versión que el binario, así que detecta una descarga dañada o truncada, pero no una versión cuyos archivos hayan sido reemplazados. La atestación siguiente comprueba que el binario se compiló mediante el flujo de trabajo de versiones de este repositorio.

En las versiones posteriores a la 1.9.0, cada binario también tiene una atestación firmada de procedencia de compilación, que muestra qué ejecución del flujo de trabajo, commit y etiqueta lo generaron, y una SBOM SPDX (shipyard-<os>-<arch>.sbom.json; .exe.sbom.json en Windows) que enumera los componentes usados para compilarlo. Verifica la atestación con la CLI de GitHub, indicando la versión que descargaste (aquí, 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

Conserva --source-ref: sin él, la comprobación se aprueba para cualquier elemento firmado por una copia del flujo de trabajo en cualquier rama, no solo para la compilación de esa etiqueta de versión.

La comprobación identifica la etiqueta, no su commit. Las atestaciones de una versión retirada no se eliminan, así que, si alguna vez se vuelve a publicar una versión con la misma etiqueta, sus binarios retirados seguirán pasando la comprobación. Para fijar también el commit, añade --source-digest <commit SHA> con el commit al que apunta la etiqueta.

Volver a compilar una versión

Las versiones posteriores a la 1.10.0 son reproducibles: volver a compilar la etiqueta de la versión, con las mismas versiones de Go y GoReleaser, genera binarios idénticos byte por byte en cualquier directorio. Las versiones son GO_VERSION y GORELEASER_VERSION en el .github/workflows/release.yaml de esa etiqueta. Con esa versión de GoReleaser instalada y GO_VERSION en lugar de 1.26.11 a continuación (GOTOOLCHAIN hace que Go use exactamente esa versión y la descarga si es necesario, y GOFLAGS= descarta tus propios indicadores de compilación):

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

El resumen debe coincidir con la misma línea del checksums.txt de la versión. Si no coincide, comprueba las versiones de Go y GoReleaser (GOTOOLCHAIN=go1.26.11 go version, goreleaser --version) antes de sospechar de la versión. El flujo de trabajo de versiones lo comprueba en cada commit de versión antes de compilarla (scripts/check-reproducible.sh). Las SBOM no son reproducibles: registran cuándo se generaron. La entrada del propio módulo de la CLI muestra la versión (devel), porque la compilación omite la marca VCS de Go; shipyard --version imprime la versión de la publicación.

Actualización

shipyard upgrade

shipyard update hace lo mismo. Instala la versión más reciente y muestra sus notas de publicación. Una instalación de Homebrew se actualiza con brew upgrade shipyard; cualquier otra instalación descarga el binario de la versión, lo verifica con el checksums.txt de la versión y reemplaza el binario en ejecución. Si ese binario está en un directorio en el que no puedes escribir, como /usr/local/bin, ejecuta sudo shipyard upgrade.

Añade --prerelease para incluir versiones preliminares, o --force para reinstalar la versión actual (si la instalaste con Homebrew, usa brew reinstall shipyard en su lugar).

Actualizar desde la versión 1.9.0 o anterior

El shipyard update de la versión 1.9.0 y anteriores compara las versiones como texto, por lo que informa que la 1.10.0 y las posteriores son anteriores a la que tienes. Actualiza una vez siguiendo el método de instalación que usaste, y shipyard upgrade funcionará a partir de entonces:

• Linux y macOS: curl https://www.shipyard.sh/install.sh | bash
• Windows: descarga el ejecutable desde la página de versiones
• Homebrew: brew upgrade shipyard

Avisos de actualización

Cuando hay una nueva versión, la CLI te avisa al terminar un comando, como máximo una vez al día:

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

Nunca pregunta nada ni espera una respuesta. La comprobación se ejecuta en segundo plano mientras se ejecuta el comando; si no ha terminado cuando el comando finaliza, la CLI espera como máximo un segundo. Esto solo ocurre cuando consulta GitHub, aproximadamente una vez al día o para obtener las notas de publicación que te hayas perdido. La primera ejecución después de una actualización realizada de cualquier otra forma, como brew upgrade, muestra esas notas.

El mensaje se envía a stderr y solo cuando stderr es una terminal. Nunca se muestra en CI, dentro de agentes de programación con IA que se identifican (Claude Code, Codex, el agente de Cursor, Gemini CLI), ni para shipyard mcp serve. Para desactivarlo, establece SHIPYARD_NO_UPDATE_CHECK=1 o añade update_check: false a ~/.shipyard/config.yaml.

Desactivar la actualización automática

En una instalación autohospedada de Shipyard que no pueda acceder a GitHub, la CLI se incluye con la versión de Shipyard. Desactiva allí la actualización automática con self_update: false en ~/.shipyard/config.yaml, o con SHIPYARD_SELF_UPDATE=false. La CLI entonces nunca se comunica con GitHub: no muestra avisos de actualización, no realiza comprobaciones en segundo plano desde shipyard mcp serve y shipyard upgrade se niega a ejecutarse con un mensaje que indica que la actualización automática está desactivada. update_check: false solo desactiva el aviso y la comprobación en segundo plano.

Inicio de sesión

Ejecuta shipyard login para inicializar la CLI. Se te pedirá que inicies sesión en Shipyard desde el navegador. Luego, la CLI guardará tu token de API en una configuración local. Ya puedes empezar a ejecutar comandos.

Shipyard autohospedado

Para usar una instalación autohospedada de Shipyard, antes de iniciar sesión, indica a la CLI que use su API en ~/.shipyard/config.yaml (o con SHIPYARD_API_URL):

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

shipyard login abrirá entonces la página de inicio de sesión de ese host, y todos los comandos llamarán a esa API. Establece self_update: false si la instalación no puede acceder a GitHub (consulta Desactivar la actualización automática).

Si ya has iniciado sesión en otra instalación de Shipyard (como shipyard.build), shipyard login conserva ese token e indica que ya has iniciado sesión. Elimina api_token del archivo de configuración (y desactiva SHIPYARD_API_TOKEN) antes de iniciar sesión en la instalación autohospedada.

O establecer el token manualmente

Establece tu token de API de Shipyard como valor de la variable de entorno SHIPYARD_API_TOKEN.

Puedes obtenerlo en tu página de perfil.

Puedes ponerte en contacto con nosotros en support@shipyard.build si quieres habilitar el acceso a la API para tu organización. Si tienes otras preguntas, puedes unirte a nuestra comunidad en Slack.

shipyard set token

También puedes usar un archivo de configuración que, de forma predeterminada, se guarda en $HOME/.shipyard/config.yaml. La primera vez que ejecutes la CLI, se creará una configuración vacía predeterminada que podrás editar.

También puedes especificar una ruta de configuración no predeterminada con la opción --config {path} añadida a cualquier comando.

Añade los valores de configuración que quieras y asegúrate de que el archivo siga la sintaxis YAML. Por ejemplo:

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

Los valores de las variables de entorno prevalecen sobre los valores correspondientes de la configuración.

Uso básico

Obtener todas las organizaciones de las que eres miembro

shipyard get orgs

Establecer la organización predeterminada global

shipyard set org {org-name}

Obtener la organización configurada actualmente

shipyard get org

Enumerar todos los entornos

shipyard get environments

Opciones disponibles:

Nombre	Descripción	Tipo	Valor predeterminado
branch	Filtrar por nombre de rama	string
deleted	Devolver entornos eliminados	boolean	false
json	Imprimir la salida JSON completa	boolean	false
name	Filtrar por nombre de la aplicación	string
org-name	Filtrar por nombre de organización, si perteneces a varias	string	tu organización predeterminada
page	Número de página solicitado	int	1
page-size	Tamaño de página solicitado	int	20
pull-request-number	Filtrar por número de solicitud de incorporación de cambios	string
repo-name	Filtrar por nombre del repositorio	string

Ejemplos:

• Enumerar todos los entornos que ejecutan el repositorio flask-backend en la rama main:

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

• Enumerar todos los entornos eliminados:

shipyard get environments --deleted

Obtener los detalles de un entorno específico por su UUID

shipyard get environment {environment_uuid}

Opciones disponibles:

Nombre	Descripción	Tipo	Valor predeterminado
json	Imprimir la salida JSON completa	boolean	false
org	Organización del entorno, si perteneces a varias	string	tu organización predeterminada
bypass-token	Imprimir solo el token de omisión del entorno, para scripts	boolean	false

--bypass-token permite que un script use el token sin que nadie tenga que escribirlo ni imprimirlo:

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

Detener un entorno en ejecución

shipyard stop environment {environment_uuid}

Reiniciar un entorno detenido

shipyard restart environment {environment_uuid}

Cancelar una compilación en curso de un entorno

shipyard cancel environment {environment_uuid}

Volver a compilar un entorno

shipyard rebuild environment {environment_uuid}

Recuperar un entorno eliminado

shipyard revive environment {environment_uuid}

Implementar un entorno independiente

Crea un entorno nuevo e independiente («desacoplado») clonando una compilación de aplicación existente. Es necesario que los entornos desacoplados estén habilitados para tu organización.

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

Anula las ramas por repositorio y controla si el entorno desacoplado se vuelve a compilar con los nuevos 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

Eliminar un entorno desacoplado

Indica el UUID del entorno o el UUID de cualquiera de sus compilaciones de aplicación (el que aparece en la URL de la página de detalles de la compilación). Solo se pueden eliminar de esta forma los entornos desacoplados; se rechazará la operación para un entorno base, de solicitud de incorporación de cambios o remoto. Si el entorno ya está eliminado, la operación vuelve a completarse correctamente.

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

Obtener todos los servicios y puertos expuestos de un entorno

shipyard get services --env {environment_uuid}

Ejecutar comandos en el servicio de un entorno en ejecución

Ejecuta cualquier comando con los argumentos y opciones que quieras en un servicio de un entorno en ejecución. Pasa los argumentos del comando después de una doble barra. La sesión evita que el entorno se detenga por inactividad solo mientras escribes en ella, hasta un máximo de 12 horas.

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

Redirigir un puerto del servicio de un entorno en ejecución

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

Un port-forward o logs --follow abierto evita que el entorno se detenga por inactividad durante un máximo de 12 horas.

Obtener los registros del servicio de un entorno en ejecución

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

Visitar un entorno

shipyard visit {environment_uuid}

Opciones disponibles:

Nombre	Descripción	Tipo	Valor predeterminado
follow	Seguir la salida de los registros	boolean	false
tail	Número de líneas recientes de registros que se mostrarán	int	3000

Trabajar con volúmenes

Enumerar todos los volúmenes de un entorno

shipyard get volumes --env {environment_uuid}

Enumerar todas las instantáneas de volúmenes de un entorno

shipyard get snapshots --env {environment_uuid}

Restablecer un volumen de un entorno

shipyard reset volume --env {environment_uuid}

Crear una instantánea en un entorno

shipyard create snapshot --env {environment_uuid}

Cargar una instantánea de volumen en un entorno

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

Subir un archivo a un volumen de un entorno

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

Llamar directamente a la API REST

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

Las rutas deben comenzar por /api/v1 o /api/v2; tu token y organización se añaden automáticamente. Las credenciales de bypass_token y kubeconfig se ocultan, a menos que pases --include-secrets.

Conectarse a Telepresence

shipyard telepresence connect --env {environment_uuid}

Desde allí, podrás comunicarte directamente con todos los pods del espacio de nombres. Puede que tengas que usar el nombre de host del espacio de nombres para comunicarte con los servicios; puedes obtenerlo en telepresence status en el campo Namespace. Por ejemplo, para comunicarte con redis, usarías redis.shipyard-app-build-{uuid}

Compilar un ejecutable a partir del código:

Puedes crear un ejecutable ejecutando el siguiente comando:

make

Para ejecutar este nuevo ejecutable:

./shipyard

Habilitar el autocompletado

Bash

Este script depende del paquete bash-completion. Si aún no está instalado, puedes instalarlo mediante el gestor de paquetes de tu sistema operativo. Para cargar las sugerencias de autocompletado en la sesión actual del shell:

source <(shipyard completion bash)

Para cargar las sugerencias de autocompletado en cada nueva sesión, ejecuta lo siguiente una vez.

En Linux:

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

En macOS:

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

Zsh

Si el autocompletado del shell aún no está habilitado en tu entorno, tendrás que habilitarlo. Puedes ejecutar lo siguiente una vez:

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

Para cargar las sugerencias de autocompletado en la sesión actual del shell:

source <(shipyard completion zsh); compdef _shipyard shipyard

Para cargar las sugerencias de autocompletado en cada nueva sesión, ejecuta lo siguiente una vez.

En Linux:

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

En macOS:

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

Tendrás que iniciar un nuevo shell para que esta configuración surta efecto.

Fish

Para cargar las sugerencias de autocompletado en la sesión actual del shell:

$ shipyard completion fish | source

Para cargar las sugerencias de autocompletado en cada sesión, ejecuta lo siguiente una vez:

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

PowerShell

Para cargar las sugerencias de autocompletado en la sesión actual del shell:

shipyard completion powershell | Out-String | Invoke-Expression

Para cargar las sugerencias de autocompletado en cada nueva sesión, ejecuta:

shipyard completion powershell > shipyard.ps1

y carga este archivo desde tu perfil de PowerShell.

Usar Shipyard desde un asistente de IA (MCP)

shipyard mcp serve ejecuta un servidor Model Context Protocol, por lo que un asistente como Claude Code, Claude Desktop, Cursor o Codex puede enumerar, inspeccionar, reconstruir y configurar tus entornos, leer los registros de los servicios, administrar volúmenes y verificar un cambio enviado frente a su entorno.

Con la CLI iniciada, añádela a Claude Code:

claude mcp add shipyard -- shipyard mcp serve

Luego, puedes hacer preguntas como:

• "¿Qué entornos están en ejecución para el repositorio web?"
• "Muéstrame los registros del servicio api en el entorno de mi rama."
• "¿Por qué falló la última compilación de este entorno?"
• "Configura FEATURE_FLAGS=beta en este entorno y reinicia el servicio worker."
• "Acabo de enviar un cambio. Verifícalo en su entorno." (o /mcp__shipyard__verify)

Consulta la guía de MCP para configurarlo en otros clientes, ver la configuración, la lista completa de herramientas, el prompt verify y la solución de problemas.