Shipyard

A CLI do Shipyard

Uma ferramenta para gerenciar ambientes efêmeros na plataforma Shipyard.

Usando um assistente de IA? A CLI inclui um servidor MCP: consulte Use o Shipyard em um assistente de IA.

Instalação

• Linux e macOS

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

  Ela é instalada em /usr/local/bin, usando sudo somente se não puder gravar nesse local. Para instalar em outro lugar, como um diretório de sua propriedade, defina SHIPYARD_INSTALL_DIR:

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

• Windows Acesse a página de releases e baixe o executável para Windows.

• Homebrew

  brew tap shipyard/tap
  brew install shipyard
  

Verificar um download

Cada release publica um checksums.txt com o SHA-256 de cada binário. O script de instalação verifica o binário com base nele e se recusa a instalar em caso de divergência. Para verificar um binário que você baixou:

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

checksums.txt vem da mesma release que o binário, então detecta um download corrompido ou truncado, mas não uma release cujos arquivos foram substituídos. A atestação abaixo verifica se o binário foi compilado pelo fluxo de trabalho de release deste repositório.

Nas releases posteriores à 1.9.0, cada binário também tem uma atestação assinada de proveniência da compilação, que mostra qual execução do fluxo de trabalho, commit e tag o compilou, além de uma SBOM SPDX (shipyard-<os>-<arch>.sbom.json; .exe.sbom.json no Windows) que lista os componentes usados na compilação. Verifique a atestação com a CLI do GitHub, informando a release que você baixou (neste exemplo, 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

Mantenha --source-ref: sem ele, a verificação é aprovada para qualquer coisa assinada por uma cópia do fluxo de trabalho em qualquer branch, não apenas pela compilação da tag daquela release.

A verificação identifica a tag, não o commit dela. As atestações de uma release retirada não são excluídas; portanto, se uma versão for lançada novamente com a mesma tag, os binários retirados ainda serão aprovados. Para fixar também o commit, adicione --source-digest <commit SHA> com o commit para o qual a tag aponta.

Recompilar uma release

As releases posteriores à 1.10.0 são reproduzíveis: compilar novamente a tag da release, com as mesmas versões do Go e do GoReleaser, gera binários idênticos byte a byte em qualquer diretório. As versões são GO_VERSION e GORELEASER_VERSION no .github/workflows/release.yaml dessa tag. Com essa versão do GoReleaser instalada e GO_VERSION no lugar de 1.26.11 abaixo (GOTOOLCHAIN faz o Go usar exatamente essa versão, baixando-a se necessário, e GOFLAGS= descarta quaisquer flags de compilação definidas por você):

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

O digest deve corresponder à mesma linha no checksums.txt da release. Se não corresponder, confira as versões do Go e do GoReleaser (GOTOOLCHAIN=go1.26.11 go version, goreleaser --version) antes de suspeitar da release. O fluxo de trabalho da release verifica isso em cada commit de release antes de compilá-la (scripts/check-reproducible.sh). As SBOMs não são reproduzíveis: elas registram quando foram geradas. A entrada do próprio módulo da CLI mostra a versão (devel), porque a compilação omite o carimbo VCS do Go; shipyard --version exibe a versão da release.

Atualização

shipyard upgrade

shipyard update faz a mesma coisa. Instala a release mais recente e exibe as notas da release. Uma instalação do Homebrew é atualizada com brew upgrade shipyard; qualquer outra instalação baixa o binário da release, verifica-o com base no checksums.txt da release e substitui o binário em execução. Se esse binário estiver em um diretório no qual você não pode gravar, como /usr/local/bin, execute sudo shipyard upgrade.

Adicione --prerelease para incluir pré-releases ou --force para reinstalar a release atual (em uma instalação do Homebrew, use brew reinstall shipyard).

Atualização a partir da versão 1.9.0 ou anterior

O shipyard update na versão 1.9.0 e anteriores compara versões como texto, então informa que a versão 1.10.0 e posteriores são mais antigas do que a versão instalada. Faça uma atualização única pelo método usado na instalação; depois disso, shipyard upgrade funcionará:

• Linux e macOS: curl https://www.shipyard.sh/install.sh | bash
• Windows: baixe o executável na página de releases
• Homebrew: brew upgrade shipyard

Avisos de atualização

Quando uma nova release estiver disponível, a CLI avisará após a conclusão de um comando, no máximo uma vez por dia:

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

Ela nunca faz perguntas nem aguarda uma resposta. A verificação é executada em segundo plano enquanto o comando está em execução; se não tiver terminado quando o comando terminar, a CLI aguardará no máximo um segundo. Isso só acontece quando ela consulta o GitHub, aproximadamente uma vez por dia, ou busca notas de release que você ainda não viu. A primeira execução após uma atualização feita de outra forma, como brew upgrade, exibe essas notas.

A mensagem é enviada para stderr e somente quando stderr é um terminal. Ela nunca é exibida em CI, em agentes de programação com IA que se identificam (Claude Code, Codex, agente do Cursor, Gemini CLI) nem para shipyard mcp serve. Para desativá-la, defina SHIPYARD_NO_UPDATE_CHECK=1 ou adicione update_check: false a ~/.shipyard/config.yaml.

Desativar a atualização automática

Em uma instalação auto-hospedada do Shipyard que não consegue acessar o GitHub, a CLI vem junto com a release do Shipyard. Desative a atualização automática nesse caso com self_update: false em ~/.shipyard/config.yaml ou com SHIPYARD_SELF_UPDATE=false. A CLI então nunca entra em contato com o GitHub: sem aviso de atualização, sem verificação em segundo plano de shipyard mcp serve e shipyard upgrade recusa a operação com uma mensagem informando que a atualização automática está desativada. update_check: false desativa somente o aviso e a verificação em segundo plano.

Login

Execute shipyard login para inicializar a CLI. Será solicitado que você faça login no Shipyard pelo navegador. Em seguida, a CLI salvará seu token de API em uma configuração local. Agora você pode começar a executar comandos.

Shipyard auto-hospedado

Para usar uma instalação auto-hospedada do Shipyard, aponte a CLI para a API dela em ~/.shipyard/config.yaml (ou com SHIPYARD_API_URL) antes de fazer login:

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

shipyard login abrirá a página de login desse host, e todos os comandos chamarão essa API. Defina self_update: false se a instalação não puder acessar o GitHub (consulte Desativar a atualização automática).

Se você já tiver feito login em outra instalação do Shipyard (como shipyard.build), shipyard login manterá esse token e informará que você já está conectado. Remova api_token do arquivo de configuração (e desconfigure SHIPYARD_API_TOKEN) antes de fazer login na instalação auto-hospedada.

Ou defina seu token manualmente

Defina seu token de API do Shipyard como o valor da variável de ambiente SHIPYARD_API_TOKEN.

Você pode obtê-lo acessando sua página de perfil.

Entre em contato conosco pelo endereço support@shipyard.build se quiser habilitar o acesso à API para sua organização. Se tiver outras dúvidas, fique à vontade para participar da nossa comunidade no Slack.

shipyard set token

Como alternativa, você pode usar um arquivo de configuração armazenado em $HOME/.shipyard/config.yaml por padrão. Na primeira vez que você executar a CLI, ela criará uma configuração vazia padrão que poderá ser editada.

Você também pode especificar um caminho de configuração diferente do padrão com a flag --config {path} adicionada a qualquer comando.

Adicione os valores de configuração ao arquivo e verifique se ele segue a sintaxe YAML. Por exemplo:

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

Os valores das variáveis de ambiente substituem os valores correspondentes na configuração.

Uso básico

Obter todas as organizações das quais você é membro

shipyard get orgs

Definir a organização padrão global

shipyard set org {org-name}

Obter a organização configurada atualmente

shipyard get org

Listar todos os ambientes

shipyard get environments

Flags disponíveis:

Nome	Descrição	Tipo	Valor padrão
branch	Filtrar pelo nome da branch	string
deleted	Retornar ambientes excluídos	boolean	false
json	Exibir a saída JSON completa	boolean	false
name	Filtrar pelo nome do aplicativo	string
org-name	Filtrar pelo nome da organização, se você fizer parte de várias organizações	string	sua organização padrão
page	Número da página solicitada	int	1
page-size	Tamanho da página solicitada	int	20
pull-request-number	Filtrar pelo número do pull request	string
repo-name	Filtrar pelo nome do repositório	string

Exemplos:

• Listar todos os ambientes que executam o repositório flask-backend na branch main:

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

• Listar todos os ambientes excluídos:

shipyard get environments --deleted

Obter detalhes de um ambiente específico pelo UUID

shipyard get environment {environment_uuid}

Flags disponíveis:

Nome	Descrição	Tipo	Valor padrão
json	Exibir a saída JSON completa	boolean	false
org	Organização do ambiente, se você fizer parte de várias organizações	string	sua organização padrão
bypass-token	Exibir somente o token de bypass do ambiente, para scripts	boolean	false

--bypass-token permite que um script use o token sem que ninguém precise digitá-lo ou exibi-lo:

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

Parar um ambiente em execução

shipyard stop environment {environment_uuid}

Reiniciar um ambiente parado

shipyard restart environment {environment_uuid}

Cancelar uma compilação em andamento de um ambiente

shipyard cancel environment {environment_uuid}

Recompilar um ambiente

shipyard rebuild environment {environment_uuid}

Reativar um ambiente excluído

shipyard revive environment {environment_uuid}

Implantar um ambiente independente

Crie um ambiente novo e independente ("detached") clonando uma compilação de aplicativo existente. É necessário que os ambientes independentes estejam habilitados para sua organização.

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

Substitua as branches por repositório e controle se o ambiente independente será recompilado quando houver novos 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

Excluir um ambiente independente

Informe o UUID do ambiente ou o UUID de qualquer uma das compilações do aplicativo (o que aparece no URL da página de detalhes da compilação). Somente ambientes independentes podem ser excluídos dessa forma; ambientes base, de pull request ou remotos não são aceitos. Excluir novamente um ambiente que já foi excluído também é permitido.

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

Obter todos os serviços e as portas expostas de um ambiente

shipyard get services --env {environment_uuid}

Executar comandos em um serviço de um ambiente em execução

Execute qualquer comando, com quaisquer argumentos e flags, em um serviço de um ambiente em execução. Passe os argumentos do comando após uma barra dupla. A sessão impede que o ambiente seja parado por inatividade somente enquanto você digita nela, por até 12 horas.

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

Encaminhar uma porta de um serviço de um ambiente em execução

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

Um port-forward ou logs --follow aberto impede que o ambiente seja parado por inatividade por até 12 horas.

Obter logs de um serviço de um ambiente em execução

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

Acessar um ambiente

shipyard visit {environment_uuid}

Flags disponíveis:

Nome	Descrição	Tipo	Valor padrão
follow	Acompanhar a saída dos logs	boolean	false
tail	Número de linhas recentes de log a exibir	int	3000

Trabalhar com volumes

Listar todos os volumes de um ambiente

shipyard get volumes --env {environment_uuid}

Listar todos os snapshots de volume de um ambiente

shipyard get snapshots --env {environment_uuid}

Redefinir um volume em um ambiente

shipyard reset volume --env {environment_uuid}

Criar um snapshot em um ambiente

shipyard create snapshot --env {environment_uuid}

Carregar um snapshot de volume em um ambiente

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

Enviar um arquivo para um volume em um ambiente

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

Chamar a API REST diretamente

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

Os caminhos devem começar com /api/v1 ou /api/v2; seu token e sua organização são adicionados automaticamente. bypass_token e as credenciais do kubeconfig são ocultados, a menos que você passe --include-secrets.

Conectar ao Telepresence

shipyard telepresence connect --env {environment_uuid}

A partir daí, você poderá se comunicar diretamente com todos os pods no namespace. Talvez seja necessário usar o hostname do namespace para se comunicar com os serviços, que você pode obter em telepresence status no campo Namespace. Por exemplo, para se comunicar com o redis, você usaria redis.shipyard-app-build-{uuid}

Criar executável a partir do código:

Você pode criar um executável executando o seguinte comando:

make

Para executar esse novo executável:

./shipyard

Ativar o preenchimento automático

Bash

Este script depende do pacote bash-completion. Se ele ainda não estiver instalado, você pode instalá-lo pelo gerenciador de pacotes do seu sistema operacional. Para carregar as conclusões na sessão atual do shell:

source <(shipyard completion bash)

Para carregar as conclusões em cada nova sessão, execute o seguinte uma vez.

No Linux:

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

No macOS:

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

Zsh

Se o preenchimento de comandos do shell ainda não estiver ativado no seu ambiente, será necessário ativá-lo. Você pode executar o seguinte uma vez:

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

Para carregar as conclusões na sessão atual do shell:

source <(shipyard completion zsh); compdef _shipyard shipyard

Para carregar as conclusões em cada nova sessão, execute o seguinte uma vez.

No Linux:

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

No macOS:

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

Você precisará iniciar um novo shell para que essa configuração entre em vigor.

Fish

Para carregar as conclusões na sessão atual do shell:

$ shipyard completion fish | source

Para carregar as conclusões em cada sessão, execute uma vez:

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

PowerShell

Para carregar as conclusões na sessão atual do shell:

shipyard completion powershell | Out-String | Invoke-Expression

Para carregar as conclusões em cada nova sessão, execute:

shipyard completion powershell > shipyard.ps1

e carregue esse arquivo no seu perfil do PowerShell.

Usar o Shipyard com um assistente de IA (MCP)

shipyard mcp serve executa um servidor Model Context Protocol, para que um assistente como Claude Code, Claude Desktop, Cursor ou Codex possa listar, inspecionar, reconstruir e configurar seus ambientes, ler logs de serviços, gerenciar volumes e verificar uma alteração enviada em relação ao ambiente correspondente.

Com a CLI autenticada, adicione-a ao Claude Code:

claude mcp add shipyard -- shipyard mcp serve

Em seguida, faça perguntas como:

• "Quais ambientes estão em execução para o repositório web?"
• "Mostre os logs do serviço api no ambiente da minha branch."
• "Por que a compilação mais recente deste ambiente falhou?"
• "Defina FEATURE_FLAGS=beta neste ambiente e reinicie o serviço worker."
• "Acabei de enviar uma alteração. Verifique-a em relação ao ambiente correspondente." (ou /mcp__shipyard__verify)

Consulte o guia de MCP para saber como configurá-lo em outros clientes, ver as opções de configuração, a lista completa de ferramentas, o prompt verify e as instruções para solução de problemas.