shipyard-cli

The Shipyard CLI is a command-line tool for managing Ephemeral Environments on the Shipyard platform. It provides commands to login, set configuration, view and manage environments, services, and volumes, and to perform actions such as starting, stopping, rebuilding, or reviving environments. Once authenticated, you can list environments, inspect details, manage services within an environment, port-forward to services, execute commands inside a running service, and fetch logs. The CLI is designed to streamline workflows for deploying and testing ephemeral environments directly from the terminal or within automation scripts.

Prerequisites:

• Docker installed and running on your machine (for the recommended docker-based setup).
• Optional: Shipyard accounts and API access to your organization.

Installation (Docker option):

1. Ensure Docker is installed and running on your system.

2. Pull and run the Shipyard CLI from its container image:

   docker run -it --rm shipyard/shipyard-cli

3. Authenticate by setting your API token in the environment (or login via the CLI if the image supports it). Example using an environment variable:

   docker run -it --rm -e SHIPYARD_API_TOKEN=your_token_here shipyard/shipyard-cli login

4. Once authenticated, you can run Shipyard CLI commands such as:

   shipyard get environments shipyard get environment {environment_uuid} shipyard exec --env {environment_uuid} --service {service_name} -- bash

If you prefer not to use Docker, you can install the Shipyard CLI directly via your platform’s package manager following the official documentation, then run the shipyard commands from your host.

Notes:

• If you use a non-default config path, you can pass --config /path/to/config.yaml to commands that support it.

Environment variable handling: The Shipyard CLI reads configuration from the local config file (default at $HOME/.shipyard/config.yaml) and from environment variables (e.g., SHIPYARD_API_TOKEN) which override config values. When using Docker, you can pass environment variables with -e to the container. If you encounter authentication issues, ensure your token is valid and has the necessary API access. For port-forwarding and exec operations, ensure your local network allows the necessary connections and that the target environment is running. If you need to persist configuration across runs, consider mounting a local config directory into the Docker container or using a non-Docker installation.

Common issues:

• Token not found or invalid: re-authenticate with shipyard login or set SHIPYARD_API_TOKEN.
• Cannot access environment: verify environment UUID and that the environment is in a running state.
• Docker image pull failures: ensure network access and that the image name is correct.