Shipyard CLI

Welcome to Shipyard's CLI feature. You can download this to your local environment and connect to your Shipyard account to access, manage, port forward or exec into your containers. The first step is to download the CLI package with the instructions below.

Installation

You can also find the installation instructions on the open-source Github repo. Follow the instructions below for your operating system or package manager.

Linux and macOS

On Linux and macOS's inbuilt terminal cimply use the curl command to install:

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

Windows

Navigate to releases page and download the executable.

You have 2 options depending on your systems architecture, either shipyard-windows-amd64.exe for AMD64 or shipyard-windows-arm64.exe for ARM64.

Homebrew

If you use homebrew on your system you can easily donload the CLI with the following two lines of code:

brew tap shipyard/tap
brew install shipyard

Get your token

Set the environment variable SHIPYARD_API_TOKEN to your Shipyard API token. You can get it by going to your profile page.

Set a Shipyard token

shipyard set token

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.

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:

SHIPYARD_API_TOKEN: <your-token>
ORG: <your-non-default-org>

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

Basic usage

If you are a part of multiple organizations that use Shipyard, then you can list the organizations and set your default org:

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

After you have set up your org, you can list a few details of all your environments and their current state. This list includes the UUID for each environment, which you will use to manage that environment through the CLI.

note

You should likely run this command each time you connect to your Shipyard containers to get the information and UUID to manage those containers.

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

If you want to see the services running for a particular environment and to know the associated ports- run this:

shipyard get environment {environment_uuid}

Available flags:

Name	Description	Type	Default Value
json	Print the complete JSON output	boolean	false
org-name	Filter by org name, if you are part of multiple orgs	string	your default org

Managing your environemnts

Now that you have the information you need, such as the UUID, available services and their associated ports, you can start managing your containers locally.

Stop a running environment

shipyard stop environment {environment_uuid}

Restart a stopped environment

shipyard restart environment {environment_uuid}

note

You can't restart a cancelled environment, you have to rebuild instead.

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}

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

Use this function to port forward a service from a running environment to a local host port. The service_port is the service's internal (contianer) port.

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

Get logs for a running environment's service

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

Available flags:

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

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.