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
  

• Windows Navigate to the releases page and download the executable for Windows.

• Homebrew

  brew tap shipyard/tap
  brew install shipyard
  

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.

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.

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

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.

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}

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.