shipyard-cli

command module
v1.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

README

The Shipyard CLI

A tool to manage Ephemeral Environments on the Shipyard platform.

Using an AI assistant? The CLI includes an MCP server: see Use Shipyard from an AI assistant.

Installation

  • Linux and macOS

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

    It installs to /usr/local/bin, using sudo only if it can't write there. To install somewhere else, such as a directory you own, set SHIPYARD_INSTALL_DIR:

    curl https://www.shipyard.sh/install.sh | SHIPYARD_INSTALL_DIR="$HOME/.local/bin" bash
    
  • Windows Navigate to the releases page and download the executable for Windows.

  • Homebrew

    brew tap shipyard/tap
    brew install shipyard
    
Verifying a download

Every release publishes a checksums.txt with the SHA-256 of each binary. The install script checks the binary against it and refuses to install on a mismatch. To check a binary you downloaded yourself:

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

checksums.txt comes from the same release as the binary, so it catches a corrupted or truncated download, not a release whose files were replaced. The attestation below is the check that the binary was built by this repo's release workflow.

In releases after 1.9.0, each binary also has a signed build provenance attestation, showing which workflow run, commit and tag built it, and an SPDX SBOM (shipyard-<os>-<arch>.sbom.json; .exe.sbom.json on Windows) listing what it was built from. Verify the attestation with the GitHub CLI, naming the release you downloaded (here 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

Keep --source-ref: without it, the check passes for anything a copy of the workflow signed on any branch, not just that release's tag build.

The check names the tag, not its commit. A withdrawn release's attestations aren't deleted, so if a version is ever released again under the same tag, its withdrawn binaries still pass. To pin the commit as well, add --source-digest <commit SHA> with the commit the tag points to.

Rebuilding a release

Releases after 1.10.0 are reproducible: building the release tag again, with the same Go and GoReleaser versions, gives byte-identical binaries in any directory. The versions are GO_VERSION and GORELEASER_VERSION in that tag's .github/workflows/release.yaml. With that GoReleaser installed, and GO_VERSION in place of 1.26.10 below (GOTOOLCHAIN makes Go use exactly that version, downloading it if needed, and GOFLAGS= drops any of your own build flags):

git clone https://github.com/shipyard/shipyard-cli && cd shipyard-cli
git checkout vX.Y.Z
GOTOOLCHAIN=go1.26.10 GOFLAGS= goreleaser release --clean --skip=publish,sbom
grep " shipyard-linux-amd64$" dist/checksums.txt

The digest should match the same line in the release's checksums.txt. If it doesn't, check your Go and GoReleaser versions (GOTOOLCHAIN=go1.26.10 go version, goreleaser --version) before suspecting the release. The release workflow checks this on every release commit before it builds the release (scripts/check-reproducible.sh). SBOMs aren't reproducible: they record when they were generated. Their entry for the CLI's own module shows the version (devel), because the build leaves out Go's VCS stamp; shipyard --version prints the release version.

Upgrading

shipyard upgrade

shipyard update does the same thing. It installs the latest release and shows its release notes. A Homebrew install is upgraded with brew upgrade shipyard; any other install downloads the release binary, verifies it against the release's checksums.txt, and replaces the running binary. If that binary is in a directory you can't write to, such as /usr/local/bin, run sudo shipyard upgrade.

Add --prerelease to include pre-releases, or --force to reinstall the current release (for a Homebrew install, use brew reinstall shipyard instead).

Upgrading from 1.9.0 or earlier

The shipyard update in 1.9.0 and earlier compares versions as text, so it reports 1.10.0 and later as older than what you have. Upgrade once the way you installed, and shipyard upgrade works from then on:

  • Linux and macOS: curl https://www.shipyard.sh/install.sh | bash
  • Windows: download the executable from the releases page
  • Homebrew: brew upgrade shipyard
Update notices

When a new release is out, the CLI tells you after a command finishes, at most once a day:

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

It never asks anything or waits for input. The check runs in the background while your command runs; if it hasn't finished when the command does, the CLI waits at most a second for it. That only happens when it's asking GitHub, about once a day or to fetch release notes you missed. The first run after an upgrade made any other way, such as brew upgrade, shows those notes.

The message goes to stderr, and only when stderr is a terminal. It's never shown in CI, inside AI coding agents that identify themselves (Claude Code, Codex, Cursor's agent, Gemini CLI), or for shipyard mcp serve. To turn it off, set SHIPYARD_NO_UPDATE_CHECK=1 or add update_check: false to ~/.shipyard/config.yaml.

Turning off self-update

On a self-hosted Shipyard that can't reach GitHub, the CLI comes with your Shipyard release instead. Turn off self-update there with self_update: false in ~/.shipyard/config.yaml, or SHIPYARD_SELF_UPDATE=false. The CLI then never contacts GitHub: no update notice, no background check from shipyard mcp serve, and shipyard upgrade refuses with a message saying self-update is off. update_check: false only turns off the notice and background check.

Login

Run shipyard login to initialize the CLI. This will prompt you to log in to Shipyard in the browser. The CLI will then save your API token in a local config. You're ready to start running commands.

Self-hosted Shipyard

To use a self-hosted Shipyard, point the CLI at its API in ~/.shipyard/config.yaml (or with SHIPYARD_API_URL) before logging in:

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

shipyard login then opens that host's login page, and every command calls that API. Set self_update: false if the install can't reach GitHub (see Turning off self-update).

If you've already logged in to another Shipyard (such as shipyard.build), shipyard login keeps that token and says you're logged in. Remove api_token from the config file (and unset SHIPYARD_API_TOKEN) before logging in to the self-hosted install.

Or Set Your Token Manually

Set your Shipyard API token as the value of the SHIPYARD_API_TOKEN environment variable.

You can get it by going to your profile page.

You can get in touch with us at support@shipyard.build if you would like to enable API access for your org. If you have any other questions, feel free to join our community Slack.

shipyard set token

Alternatively, you can use a configuration file stored in $HOME/.shipyard/config.yaml by default. When you run the CLI for the first time, it will create a default empty config that you can then edit.

You can also specify a non-default config path with the --config {path} flag added to any command.

Add any configuration values in your config and ensure the file follows YAML syntax. For example:

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

The values of your environment variables override their corresponding values in the config.

Basic usage

Get all orgs you are a member of
shipyard get orgs
Set the global default org
shipyard set org {org-name}
Get the currently configured org
shipyard get org
List all environments
shipyard get environments

Available flags:

Name Description Type Default Value
branch Filter by branch name string
deleted Return deleted environments boolean false
json Print the complete JSON output boolean false
name Filter by name of the application string
org-name Filter by org name, if you are part of multiple orgs string your default org
page Page number requested int 1
page-size Page size requested int 20
pull-request-number Filter by pull request number string
repo-name Filter by repo name string

Examples:

  • List all environments running the repo flask-backend on branch main:
shipyard get environments --repo-name flask-backend --branch main
  • List all deleted environments:
shipyard get environments --deleted
Get details for a specifc environment by its UUID
shipyard get environment {environment_uuid}

Available flags:

Name Description Type Default Value
json Print the complete JSON output boolean false
org Org of the environment, if you are part of multiple orgs string your default org
bypass-token Print only the environment's bypass token, for scripts boolean false

--bypass-token lets a script use the token without anyone typing or printing it:

SHIPYARD_TOKEN=$(shipyard get environment {environment_uuid} --bypass-token) && \
  export SHIPYARD_TOKEN && curl -b "shipyard_token=$SHIPYARD_TOKEN" https://your-environment-url/
Stop a running environment
shipyard stop environment {environment_uuid}
Restart a stopped environment
shipyard restart environment {environment_uuid}
Cancel ongoing build for an environment
shipyard cancel environment {environment_uuid}
Rebuild an environment
shipyard rebuild environment {environment_uuid}
Revive a deleted environment
shipyard revive environment {environment_uuid}
Deploy a detached environment

Create a new, independent ("detached") environment by cloning an existing application build. Requires detached environments to be enabled for your org.

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

Override branches per-repo and control whether the detached environment rebuilds on new 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
Delete a detached environment

Pass the environment UUID, or the UUID of any of its application builds (the one in the build detail page's URL). Only detached environments can be deleted this way; a base, pull request or remote environment is refused. Deleting one that is already deleted succeeds again.

shipyard detached delete {environment_uuid}
shipyard detached delete {application_build_uuid}
Get all services and exposed ports for an environment
shipyard get services --env {environment_uuid}
Exec into a running environment's service

Execute any command with any arguments and flags in a given service for a running environment. Pass any command arguments after a double slash. The session keeps the environment from being stopped as idle only while you type in it, for up to 12 hours.

shipyard exec --env {environment_uuid} --service {service_name} -- bash
Port forward a running environment's service's port
shipyard port-forward --env {environment_uuid} --service {service_name} --ports {local_port}:{service_container_port}

An open port-forward or logs --follow keeps the environment from being stopped as idle for up to 12 hours.

Get logs for a running environment's service
shipyard logs --env {environment_uuid} --service {service_name}
Visit an environment
shipyard visit {environment_uuid}

Available flags:

Name Description Type Default Value
follow Follow the logs output boolean false
tail # of recent log lines to show int 3000

Work with volumes

List all volumes in an environment
shipyard get volumes --env {environment_uuid}
List all volume snapshots in an environment
shipyard get snapshots --env {environment_uuid}
Reset a volume in an environment
shipyard reset volume --env {environment_uuid}
Create a snapshot in an environment
shipyard create snapshot --env {environment_uuid}
Load a volume snapshot in an environment
shipyard load snapshot --env {environment_uuid} --sequence-number {n}
Upload a file to a volume in an environment
shipyard upload volume --env {environment_uuid} --volume {volume} --file {filepath.bz2}
Call the REST API directly
shipyard api /api/v1/environment
shipyard api -X PUT /api/v1/environment/{environment_uuid}/env-vars --input body.json

Paths must start with /api/v1 or /api/v2; your token and org are added for you. bypass_token and kubeconfig credentials are redacted unless you pass --include-secrets.

Connect to telepresence
shipyard telepresence connect --env {environment_uuid}

From there, you'll be able to communicate directly with all pods in the namespace. You may have to use the namespace hostname to communicate with services, which you can get via telepresence status under the Namespace field. For example, to communicate with redis, you'd use redis.shipyard-app-build-{uuid}

Build executable from code:

You can make an executable by running the following command:

make

To run this new executable:

./shipyard

Enable Autocompletion

Bash

This script depends on the bash-completion package. If it is not installed already, you can install it via your OS's package manager. To load completions in your current shell session:

source <(shipyard completion bash)

To load completions for every new session, execute the following once.

On Linux:

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

On macOS:

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

If shell completion is not already enabled in your environment, you will need to enable it. You can execute the following once:

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

To load completions in your current shell session:

source <(shipyard completion zsh); compdef _shipyard shipyard

To load completions for every new session, execute the following once.

On Linux:

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

On macOS:

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

You will need to start a new shell for this setup to take effect.

Fish

To load completions in your current shell session:

$ shipyard completion fish | source

To load completions for each session, execute once:

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

To load completions in your current shell session:

shipyard completion powershell | Out-String | Invoke-Expression

To load completions for every new session, run:

shipyard completion powershell > shipyard.ps1

and source this file from your PowerShell profile.

Use Shipyard from an AI assistant (MCP)

shipyard mcp serve runs a Model Context Protocol server, so an assistant such as Claude Code, Claude Desktop, Cursor or Codex can list, inspect, rebuild and configure your environments, read service logs, manage volumes, and verify a pushed change against its environment.

With the CLI logged in, add it to Claude Code:

claude mcp add shipyard -- shipyard mcp serve

Then ask things like:

  • "Which environments are running for the web repo?"
  • "Show me the api service's logs on my branch's environment."
  • "Why did the latest build of this environment fail?"
  • "Set FEATURE_FLAGS=beta on this environment and restart the worker service."
  • "I just pushed. Verify the change against its environment." (or /mcp__shipyard__verify)

See the MCP guide for setting it up in other clients, configuration, the full tool list, the verify prompt, and troubleshooting.

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
app
Package app holds the commands that set up Shipyard apps.
Package app holds the commands that set up Shipyard apps.
env
k8s
org
pkg
apps
Package apps calls core's application create, reconfigure and plan APIs.
Package apps calls core's application create, reconfigure and plan APIs.
k8s
mcp/hosted
Package hosted serves Shipyard's MCP tools over stateless Streamable HTTP for clients that connect with OAuth, instead of over stdio with the CLI's own token.
Package hosted serves Shipyard's MCP tools over stateless Streamable HTTP for clients that connect with OAuth, instead of over stdio with the CLI's own token.
selfupdate
Package selfupdate checks GitHub for new releases of the CLI, installs them, and renders their release notes in the terminal.
Package selfupdate checks GitHub for new releases of the CLI, installs them, and renders their release notes in the terminal.
zip
tests

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL