Shipyard

https://docs.shipyard.build/
Admin
Shipyard is an Environment Management platform that creates ephemeral, on-demand copies of your...
Tokens:16,963
Snippets:240
Trust Score:9.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Shipyard Configuration File Example

Source: https://docs.shipyard.build/cli

Example YAML structure for the configuration file located at $HOME/.shipyard/config.yaml.

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

--------------------------------

### Install Shipyard CLI

Source: https://docs.shipyard.build/mcp

Install the Shipyard CLI using Homebrew to enable MCP server functionality.

```bash
brew tap shipyard/tap  
brew install shipyard  
```

--------------------------------

### Configure service initialization

Source: https://docs.shipyard.build/docker-compose

Defines a command to execute before the service starts.

```yaml
shipyard.init: 'python manage.py db migrate'
```

--------------------------------

### Configure fish autocompletion

Source: https://docs.shipyard.build/cli

Setup instructions for enabling fish shell completions.

```bash
shipyard completion fish | source  
```

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

--------------------------------

### List Environments Response Examples

Source: https://docs.shipyard.build/api

Example JSON payloads and HTTP metadata for successful and unauthorized requests to the list environments endpoint.

```json
{
  "data": [
    {
      "attributes": {
        "bypass_token": "WBwQX4e_sxUgyJhkJFJzcs-oLmYPinVeogPtsJL_SV-7H7QMBN6n3TCbjcYNzRtH",
        "name": "muti-repo-app",
        "processing": false,
        "projects": [
          {
            "branch": "my-feature-branch",
            "commit_hash": "abcabc123123",
            "org_name": "shipyard",
            "pull_request_number": 1112,
            "repo_name": "flask-backend"
          },
          {
            "branch": "master",
            "commit_hash": "bcabca321321",
            "org_name": "shipyard",
            "pull_request_number": null,
            "repo_name": "flask-frontend"
          }
        ],
        "ready": true,
        "retired": false,
        "deleted": false,
        "stopped": false,
        "url": "https://shipyard-multi-repo-app-pr1112.dev.shipyardbuild.shipyard.host"
      },
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "links": {
        "self": "/api/v1/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
      },
      "type": "application"
    }
  ],
  "links": {
    "first": "/api/v1/environment?page=1",
    "last": "/api/v1/environment?page=10",
    "next": "/api/v1/environment?page=2",
    "prev": ""
  }
}
```

```http
HTTP/2 200
date: Wed, 20 Apr 2022 14:51:57 GMT
content-type: application/json
content-length: 6382
strict-transport-security: max-age=15724800; includeSubDomains
```

```json
{
  "data": [],
  "links": {
    "first": "/api/v1/environment?page=1",
    "last": "/api/v1/environment?page=1",
    "next": "",
    "prev": ""
  }
}
```

```http
HTTP/2 200
date: Wed, 20 Apr 2022 16:21:42 GMT
content-type: application/json
content-length: 17
strict-transport-security: max-age=15724800; includeSubDomains
```

```json
{
  "errors": [
    {
      "status": 401,
      "title": "Invalid token"
    }
  ]
}
```

```http
HTTP/2 401
date: Wed, 20 Apr 2022 16:16:07 GMT
content-type: application/json
content-length: 87
strict-transport-security: max-age=15724800; includeSubDomains
```

--------------------------------

### Configure PowerShell autocompletion

Source: https://docs.shipyard.build/cli

Setup instructions for enabling PowerShell completions.

```powershell
shipyard completion powershell | Out-String | Invoke-Expression  
```

```powershell
shipyard completion powershell > shipyard.ps1  
```

--------------------------------

### List environment variables response examples

Source: https://docs.shipyard.build/api

JSON responses for successful retrieval and authentication errors.

```json
{
  "data": [
    {
      "type": "env-var",
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "attributes": {
        "name": "DATABASE_URL",
        "value": "p*****************5432/mydb",
        "hidden": true,
        "services": [],
        "created_at": "2026-04-15T12:00:00",
        "updated_at": "2026-04-15T12:00:00"
      }
    },
    {
      "type": "env-var",
      "id": "ffffffff-gggg-hhhh-iiii-jjjjjjjjjjjj",
      "attributes": {
        "name": "DEBUG",
        "value": "true",
        "hidden": false,
        "services": ["web"],
        "created_at": "2026-04-15T12:00:00",
        "updated_at": "2026-04-15T12:00:00"
      }
    }
  ],
  "included": {
    "inherited": []
  }
}
```

```json
{
  "errors": [
    {
      "status": 401,
      "title": "Invalid token"
    }
  ]
}
```

--------------------------------

### Install Shipyard CLI on Linux and macOS

Source: https://docs.shipyard.build/cli

Use this command to download and install the CLI via shell script.

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

--------------------------------

### Configure Bash autocompletion

Source: https://docs.shipyard.build/cli

Setup instructions for enabling Bash shell completions.

```bash
source <(shipyard completion bash)  
```

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

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

--------------------------------

### Configure Zsh autocompletion

Source: https://docs.shipyard.build/cli

Setup instructions for enabling Zsh shell completions.

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

```bash
source <(shipyard completion zsh); compdef _shipyard shipyard  
```

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

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

--------------------------------

### Configuring Shipyard Action via Inputs

Source: https://docs.shipyard.build/github-actions

Configuration example using the 'with' keyword to pass inputs to the Shipyard action.

```yaml
  - name: Integrate Shipyard  
    uses: shipyard/shipyard-action@1.0.0  
    with:  
        api-token: ${{ secrets.SHIPYARD_API_TOKEN }}  
        timeout-minutes: 30
```

--------------------------------

### shipyard get environments

Source: https://docs.shipyard.build/cli

Lists all environments with their current states and UUIDs.

```APIDOC
## shipyard get environments

### Description
Lists details of all environments and their current states, including UUIDs.

### Flags
- **branch** (string) - Optional - Filter by branch name
- **deleted** (boolean) - Optional - Return deleted environments (default: false)
- **json** (boolean) - Optional - Print the complete JSON output (default: false)
- **name** (string) - Optional - Filter by name of the application
- **org-name** (string) - Optional - Filter by org name
- **page** (int) - Optional - Page number requested (default: 1)
- **page-size** (int) - Optional - Page size requested (default: 20)
- **pull-request-number** (string) - Optional - Filter by pull request number
- **repo-name** (string) - Optional - Filter by repo name
```

--------------------------------

### Build History Empty Response

Source: https://docs.shipyard.build/api

Example JSON response and HTTP headers when no build history is found.

```json
{
  "data": [],
  "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "links": {
    "first": "/api/v1/environment/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/build-history?page=1",
    "last": "/api/v1/environment/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/build-history?page=1",
    "next": "",
    "prev": ""
  },
  "type": "application"
}
```

```http
HTTP/2 200
date: Wed, 20 Apr 2022 16:21:42 GMT
content-type: application/json
content-length: 17
strict-transport-security: max-age=15724800; includeSubDomains
```

--------------------------------

### Enable CloudSQL sidecar

Source: https://docs.shipyard.build/docker-compose

Configures the service to start with a GCP CloudSQL sidecar container.

```yaml
shipyard.cloudsql.sidecar: true  
```

--------------------------------

### shipyard get services

Source: https://docs.shipyard.build/cli

Retrieves all services and exposed ports for an environment.

```APIDOC
## shipyard get services --env {environment_uuid}

### Description
Lists all services and their associated ports for a given environment.

### Parameters
#### Query Parameters
- **env** (string) - Required - The unique identifier of the environment.
```

--------------------------------

### Add or update environment variables response examples

Source: https://docs.shipyard.build/api

JSON responses for successful upsert operations and partial failures.

```json
{
  "data": [
    {
      "type": "env-var",
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "attributes": {
        "name": "DATABASE_URL",
        "value": "p*****************5432/mydb",
        "hidden": true,
        "services": [],
        "created_at": "2026-04-15T12:00:00",
        "updated_at": "2026-04-15T12:00:00"
      }
    },
    {
      "type": "env-var",
      "id": "ffffffff-gggg-hhhh-iiii-jjjjjjjjjjjj",
      "attributes": {
        "name": "DEBUG",
        "value": "true",
        "hidden": false,
        "services": ["web"],
        "created_at": "2026-04-15T12:00:00",
        "updated_at": "2026-04-15T12:00:00"
      }
    }
  ]
}
```

```json
{
  "data": [
    {
      "type": "env-var",
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "attributes": {
        "name": "VALID_VAR",
        "value": "some_value",
        "hidden": true,
        "services": [],
        "created_at": "2026-04-15T12:00:00",
        "updated_at": "2026-04-15T12:00:00"
      }
    }
  ],
  "errors": [
    {
      "name": null,
      "error": "name and value are required"
    }
  ]
}
```

--------------------------------

### Filter Environments

Source: https://docs.shipyard.build/cli

Examples of filtering environment lists by repository, branch, or deletion status.

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

```bash
shipyard get environments --deleted
```

--------------------------------

### Configure E2E tests with Shipyard

Source: https://docs.shipyard.build/circle-ci

Example workflow configuration using the fetch-shipyard-env command to set environment variables for testing.

```yaml
version: '2.1'  
orbs:  
  shipyard: shipyard/shipyard@1  
jobs:  
  ephemeral-e2e-tests:  
    executor:  
      name: cypress/browsers-chrome77  
    steps:  
      - checkout  
      - shipyard/fetch-shipyard-env  
      - run:  
          command: |
            export CYPRESS_BASE_URL=${SHIPYARD_ENVIRONMENT_URL}  
            export CYPRESS_BYPASS_TOKEN=${SHIPYARD_BYPASS_TOKEN}  
            npm run test  
          name: Run the e2e tests on the ephemeral environment  
workflows:  
  use-my-orb:  
    jobs:  
      - ephemeral-e2e-tests  
```

--------------------------------

### Configuring Shipyard Action via Environment Variables

Source: https://docs.shipyard.build/github-actions

Configuration example using the 'env' keyword to pass environment variables to the Shipyard action.

```yaml
  - name: Integrate Shipyard  
    uses: shipyard/shipyard-action@1.0.0  
    env:  
      SHIPYARD_API_TOKEN: ${{ secrets.SHIPYARD_API_TOKEN }}  
      SHIPYARD_TIMEOUT: 30
```

--------------------------------

### Get Environment Details

Source: https://docs.shipyard.build/cli

Retrieve service and port information for a specific environment using its UUID.

```bash
shipyard get environment {environment_uuid}
```

--------------------------------

### Configure liveness probe initial delay

Source: https://docs.shipyard.build/docker-compose

Sets the wait time in seconds before starting probes.

```yaml
shipyard.liveness.initial_delay: 10
```

--------------------------------

### Build History Success Response

Source: https://docs.shipyard.build/api

Example JSON response and HTTP headers for a successful build history retrieval.

```json
{
  "data": {
      "builds": [
        {
          "id": "111222-ccccc-ddddd-5555",
          "projects": [
            {
              "branch": "my-feature-branch",
              "commit_hash": "abcabc123123",
              "repo_owner": "shipyard",
              "pull_request_number": 1112,
              "repo_name": "flask-backend"
            },
            {
              "branch": "master",
              "commit_hash": "bcabca321321",
              "repo_owner": "shipyard",
              "pull_request_number": null,
              "repo_name": "flask-frontend"
            }
          ],
          "successfully_built": true,
          "queued_at": "2022-04-20T20:02:00.039498Z"
        },
        {
          "id": "111222-ccccc-ddddd-214s",
          "projects": [
            {
              "branch": "my-feature-branch",
              "commit_hash": "abcabc123567",
              "repo_owner": "shipyard",
              "pull_request_number": 1112,
              "repo_name": "flask-backend"
            },
            {
              "branch": "master",
              "commit_hash": "bcabca321321",
              "repo_owner": "shipyard",
              "pull_request_number": null,
              "repo_name": "flask-frontend"
            }
          ],
          "successfully_built": false,
          "queued_at": "2022-04-19T20:02:00.039498Z"
        },
      ],
      "name": "flask-starter-app"
  },
  "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  "links": {
    "first": "/api/v1/environment/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/build-history?page=1",
    "last": "/api/v1/environment/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/build-history?page=10",
    "next": "/api/v1/environment/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/build-history?page=2",
    "prev": ""
  },
  "type": "application"
}
```

```http
HTTP/2 200
date: Wed, 20 Apr 2022 14:51:57 GMT
content-type: application/json
content-length: 6382
strict-transport-security: max-age=15724800; includeSubDomains
```

--------------------------------

### Configure liveness probe HTTP path

Source: https://docs.shipyard.build/docker-compose

Sets the GET path for the liveness probe.

```yaml
shipyard.liveness.http.path: /healthz
```

--------------------------------

### GET https://shipyard.build/api/v1/environment/${app_uuid}

Source: https://docs.shipyard.build/api

Retrieves the details of a specific environment using its unique UUID.

```APIDOC
## GET https://shipyard.build/api/v1/environment/${app_uuid}

### Description
Get an environment by UUID.

### Method
GET

### Endpoint
https://shipyard.build/api/v1/environment/${app_uuid}

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - The unique identifier of the environment

### Response
#### Success Response (200)
- **200** - Success

#### Error Response (404)
- **404** - Environment not found
```

--------------------------------

### Get service logs

Source: https://docs.shipyard.build/cli

Retrieves logs for a specific service in a running environment.

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

--------------------------------

### shipyard get org

Source: https://docs.shipyard.build/cli

Retrieves the currently configured default organization.

```APIDOC
## shipyard get org

### Description
Displays the currently configured default organization.
```

--------------------------------

### Shipyard GitHub Action Workflow Integration

Source: https://docs.shipyard.build/github-actions

Example of a GitHub workflow step that integrates Shipyard to fetch environment variables for E2E testing.

```yaml
on: [pull_request]  
  
jobs:  
  cypress-e2e-tests:  
    runs-on: ubuntu-latest  
    name: Collect the bypass token and URL for an authenticated ephemeral environment attached to this PR in order to run E2E tests on it.  
    steps:  
      - name: Checkout  
        uses: actions/checkout@v2  
      - name: Integrate Shipyard  
        uses: shipyard/shipyard-action@1.0.0  
        env:  
          SHIPYARD_API_TOKEN: ${{ secrets.SHIPYARD_API_TOKEN }}  
      - name: Run the E2E tests against the ephemeral environment  
        run: npm run test  
        shell: bash  
        env:  
            CYPRESS_BASE_URL: $SHIPYARD_ENVIRONMENT_URL  
            CYPRESS_BYPASS_TOKEN: $SHIPYARD_BYPASS_TOKEN
```

--------------------------------

### GET https://shipyard.build/api/v1/environment/${app_uuid}/env-vars

Source: https://docs.shipyard.build/api

Retrieves a list of all environment variables associated with a specific environment.

```APIDOC
## GET https://shipyard.build/api/v1/environment/${app_uuid}/env-vars

### Description
Retrieves a list of all environment variables associated with a specific environment.

### Method
GET

### Endpoint
https://shipyard.build/api/v1/environment/${app_uuid}/env-vars

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - The unique identifier of the environment.

### Response
#### Success Response (200)
- **data** (array) - List of environment variable objects.

#### Response Example
{
  "data": [
    {
      "type": "env-var",
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "attributes": {
        "name": "DATABASE_URL",
        "value": "p*****************5432/mydb",
        "hidden": true,
        "services": [],
        "created_at": "2026-04-15T12:00:00",
        "updated_at": "2026-04-15T12:00:00"
      }
    }
  ]
}
```

--------------------------------

### Get Build History cURL Request

Source: https://docs.shipyard.build/api

Retrieve the build history for a specific environment using its UUID.

```bash
curl -H 'x-api-token: ${YOUR_API_TOKEN}' "https://shipyard.build/api/v1/environment/${app_uuid}/build-history"
```

--------------------------------

### GET https://shipyard.build/api/v1/environment

Source: https://docs.shipyard.build/api

Retrieves a list of all active environments, with optional filtering by name, organization, repository, branch, or pull request number.

```APIDOC
## GET https://shipyard.build/api/v1/environment

### Description
List all active environments with support for filtering and pagination.

### Method
GET

### Endpoint
https://shipyard.build/api/v1/environment

### Parameters
#### Query Parameters
- **name** (string) - Optional - Filter by environment name
- **org_name** (string) - Optional - Filter by organization name
- **repo_name** (string) - Optional - Filter by repository name
- **branch** (string) - Optional - Filter by branch name
- **pull_request_number** (string) - Optional - Filter by PR number
- **deleted** (boolean) - Optional - Filter by deleted (default: false)
- **page** (integer) - Optional - Page number being requested (default: 1)
- **page_size** (integer) - Optional - Number of environments per page (default: 20)

### Response
#### Success Response (200)
- **data** (array) - List of environment objects
- **links** (object) - Pagination links

#### Response Example
{
  "data": [
    {
      "attributes": {
        "name": "muti-repo-app",
        "ready": true,
        "url": "https://shipyard-multi-repo-app-pr1112.dev.shipyardbuild.shipyard.host"
      },
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "type": "application"
    }
  ]
}
```

--------------------------------

### GET https://shipyard.build/api/v1/environment/${app_uuid}/build-history

Source: https://docs.shipyard.build/api

Retrieves the build history for a specific environment identified by its UUID. Supports pagination and filtering by successful builds.

```APIDOC
## GET https://shipyard.build/api/v1/environment/${app_uuid}/build-history

### Description
Retrieves the build history for a specific environment identified by its UUID.

### Method
GET

### Endpoint
https://shipyard.build/api/v1/environment/${app_uuid}/build-history

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - The unique identifier of the environment.

#### Query Parameters
- **successfully_built** (boolean) - Optional - Only return environments which were deployed successfully. Default: false
- **page** (integer) - Optional - Page number being requested. Default: 1
- **page_size** (integer) - Optional - Number of environments per page. Default: 20

### Response
#### Success Response (200)
- **data** (object) - Contains build information and environment name.
- **id** (string) - Environment ID.
- **links** (object) - Pagination links.
- **type** (string) - Resource type.
```

--------------------------------

### Get Environment by UUID via cURL

Source: https://docs.shipyard.build/api

Retrieve details for a specific environment using its unique identifier.

```bash
curl -H 'x-api-token: ${YOUR_API_TOKEN}' "https://shipyard.build/api/v1/environment/${app_uuid}"
```

--------------------------------

### Invalid UUID Error Response

Source: https://docs.shipyard.build/api

Example JSON error response and HTTP headers for a non-existent environment UUID.

```json
{
  "errors": [
    {
      "status": 404,
      "title": "Application not found!"
    }
  ]
}
```

```http
HTTP/2 404
date: Wed, 20 Apr 2022 16:16:07 GMT
content-type: application/json
content-length: 87
strict-transport-security: max-age=15724800; includeSubDomains
```

--------------------------------

### Clone the starter repository

Source: https://docs.shipyard.build/quickstart

Use these commands to clone the forked repository to your local machine.

```bash
git clone https://github.com/<YOUR_USERNAME>/react-flask-starter.git  
cd react-flask-starter  
```

--------------------------------

### Build and run executable

Source: https://docs.shipyard.build/cli

Commands to compile the project and execute the resulting binary.

```bash
make  
```

```bash
./shipyard  
```

--------------------------------

### Define post-start command

Source: https://docs.shipyard.build/docker-compose

Executes a command on the Kubernetes post-start event, provided as a JSON string.

```yaml
shipyard.lifecycle.postStart.exec.command: "[\"sh\", \"/srv/poststart.sh\"]"  
```

--------------------------------

### shipyard get orgs

Source: https://docs.shipyard.build/cli

Retrieves a list of all organizations the user is a member of.

```APIDOC
## shipyard get orgs

### Description
Lists all organizations that the user is a member of.

### Command
`shipyard get orgs`
```

--------------------------------

### Connect to telepresence

Source: https://docs.shipyard.build/cli

Establishes a connection to the environment namespace for direct pod communication.

```bash
shipyard telepresence connect --env {environment_uuid}  
```

--------------------------------

### POST /api/v1/environment/${app_uuid}/snapshot-load

Source: https://docs.shipyard.build/api

Loads a snapshot onto an environment.

```APIDOC
## POST /api/v1/environment/${app_uuid}/snapshot-load

### Description
Loads a snapshot onto an environment.

### Method
POST

### Endpoint
https://shipyard.build/api/v1/environment/${app_uuid}/snapshot-load

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - The unique identifier of the environment.

#### Request Body
- **sequence_number** (integer) - Required - Sequence number of desired snapshot to use
- **source_application_id** (string) - Optional - UUID of source environment, if different from target environment

### Response
#### Success Response (204)
- Snapshot load queued
```

--------------------------------

### Configure readiness probe thresholds and timing

Source: https://docs.shipyard.build/docker-compose

Settings for controlling probe failure thresholds, initial delays, periods, success thresholds, and timeouts.

```yaml
shipyard.readiness.failure_threshold: 1
```

```yaml
shipyard.readiness.initial_delay: 10
```

```yaml
shipyard.readiness.period: 15
```

```yaml
shipyard.readiness.success_threshold: 1
```

```yaml
shipyard.readiness.timeout_seconds: 10
```

--------------------------------

### Configure HTTP readiness probe

Source: https://docs.shipyard.build/docker-compose

Defines headers and paths for HTTP-based readiness probes.

```yaml
shipyard.readiness.http.headers: '{"x-reason": "health"}'
```

```yaml
shipyard.readiness.http.path: /healthz
```

--------------------------------

### List environment services

Source: https://docs.shipyard.build/cli

Retrieves all services and their exposed ports for a given environment.

```bash
shipyard get services --env {environment_uuid}  
```

--------------------------------

### Manage environment volumes

Source: https://docs.shipyard.build/cli

Commands for listing, resetting, and snapshotting volumes within a specific environment.

```bash
shipyard get volumes --env {environment_uuid}  
```

```bash
shipyard get snapshots --env {environment_uuid}  
```

```bash
shipyard reset volume --env {environment_uuid}  
```

```bash
shipyard create snapshot --env {environment_uuid}  
```

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

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

--------------------------------

### Invalid Token Error Response

Source: https://docs.shipyard.build/api

Example JSON error response and HTTP headers for an invalid API token.

```json
{
  "errors": [
    {
      "status": 401,
      "title": "Invalid token"
    }
  ]
}
```

```http
HTTP/2 401
date: Wed, 20 Apr 2022 16:16:07 GMT
content-type: application/json
content-length: 87
strict-transport-security: max-age=15724800; includeSubDomains
```

--------------------------------

### List Environments

Source: https://docs.shipyard.build/cli

Retrieve a list of environments and their states. Run this command frequently to ensure you have the correct environment UUIDs.

```bash
shipyard get environments
```

--------------------------------

### POST /api/v1/environment/${app_uuid}/restart

Source: https://docs.shipyard.build/api

Restarts a retired environment.

```APIDOC
## POST /api/v1/environment/${app_uuid}/restart

### Description
Restarts a retired environment.

### Method
POST

### Endpoint
https://shipyard.build/api/v1/environment/${app_uuid}/restart

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - The unique identifier of the environment.

### Response
#### Success Response (204)
- Environment restarted successfully
```

--------------------------------

### Manage Shipyard Organizations

Source: https://docs.shipyard.build/cli

Commands to list, set, and retrieve the current organization configuration.

```bash
shipyard get orgs
```

```bash
shipyard set org {org-name}
```

```bash
shipyard get org
```

--------------------------------

### POST /api/v1/environment/${app_uuid}

Source: https://docs.shipyard.build/api

Updates the branch configurations for an environment.

```APIDOC
## POST /api/v1/environment/${app_uuid}

### Description
Updates the branch configurations for an environment. You must declare repo/branch combinations for each existing repo in the environment.

### Method
POST

### Endpoint
https://shipyard.build/api/v1/environment/${app_uuid}

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - The unique identifier of the environment.

#### Request Body
- **projects** (array) - Required - Repo-branch updates

### Response
#### Success Response (200)
- Success, new build queued
```

--------------------------------

### Volume Management Tools

Source: https://docs.shipyard.build/mcp

Tools for managing environment volumes and snapshots.

```APIDOC
## MCP Tools: Volume Management

- **get_volumes**: List volumes in an environment
- **reset_volume**: Reset volume to initial state
- **get_snapshots**: List volume snapshots
- **create_snapshot**: Create volume snapshot
- **load_snapshot**: Load volume snapshot
```

--------------------------------

### Load a snapshot onto an environment via cURL

Source: https://docs.shipyard.build/api

Queues a snapshot load operation using a sequence number and optional source application ID.

```bash
curl -H "x-api-token: ${YOUR_API_TOKEN}" -H "Content-Type: application/json" -XPOST https://shipyard.build/api/v1/environment/${app_uuid}/snapshot-load --data-raw '{  
  "data": {  
    "attributes": {  
      "sequence_number": 778,  
      "source_application_id": "000-0fsdf-ljsdfk"  
    },  
    "type": "snapshot-load"  
  }
}'  
```

--------------------------------

### POST /api/v1/environment/${app_uuid}/rebuild

Source: https://docs.shipyard.build/api

Rebuilds a non-deleted environment.

```APIDOC
## POST /api/v1/environment/${app_uuid}/rebuild

### Description
Rebuilds a non-deleted environment.

### Method
POST

### Endpoint
https://shipyard.build/api/v1/environment/${app_uuid}/rebuild

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - The unique identifier of the environment.

### Response
#### Success Response (204)
- Environment rebuilt successfully
```

--------------------------------

### Configure readiness probe command

Source: https://docs.shipyard.build/docker-compose

Defines the command to be executed for the readiness probe as a JSON array.

```yaml
shipyard.readiness.exec.command: '["bash", "some-script.sh"]'
```

--------------------------------

### Set Shipyard API Token

Source: https://docs.shipyard.build/cli

Run this command to interactively set your Shipyard API token.

```bash
shipyard set token
```

--------------------------------

### Configure liveness probe HTTP headers

Source: https://docs.shipyard.build/docker-compose

Provides a JSON string of headers for HTTP probes.

```yaml
shipyard.liveness.http.headers: '{"x-reason": "health"}'
```

--------------------------------

### shipyard/fetch-shipyard-env

Source: https://docs.shipyard.build/circle-ci

A CircleCI job step that fetches environment variables for a Shipyard ephemeral environment.

```APIDOC
## shipyard/fetch-shipyard-env

### Description
This job step fetches necessary environment variables from Shipyard to allow E2E tests to run on ephemeral environments. It sets variables such as the environment URL and bypass token.

### Parameters
- **api-token** (env_var_name) - Optional - Shipyard API token used to fetch environment variables. Default: SHIPYARD_API_TOKEN.
- **timeout-minutes** (integer) - Optional - Number of minutes to wait for the Shipyard environment. Default: 60.
- **exit-if-not-pull-request** (boolean) - Optional - Gracefully exit the job if it is not for a pull request. Default: false.
- **app-name** (string) - Optional - Filter environments by the name of the application on the Shipyard app.

### Output Environment Variables
- **SHIPYARD_ENVIRONMENT_ID** - ID of the ephemeral environment.
- **SHIPYARD_ENVIRONMENT_URL** - URL of the ephemeral environment.
- **SHIPYARD_BYPASS_TOKEN** - Token to bypass authentication (Available in v3.5.1+).
```

--------------------------------

### POST /api/v1/environment/${app_uuid}/revive

Source: https://docs.shipyard.build/api

Revives a deleted environment.

```APIDOC
## POST /api/v1/environment/${app_uuid}/revive

### Description
Revives a deleted environment.

### Method
POST

### Endpoint
https://shipyard.build/api/v1/environment/${app_uuid}/revive

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - The unique identifier of the environment.

### Response
#### Success Response (204)
- Environment revived successfully
```

--------------------------------

### Configure service as a job

Source: https://docs.shipyard.build/docker-compose

Sets the service to run as a Kubernetes job.

```yaml
shipyard.job: true
```

--------------------------------

### Revive a deleted environment

Source: https://docs.shipyard.build/cli

Restores a previously deleted environment.

```bash
shipyard revive environment {environment_uuid}  
```

--------------------------------

### Configure liveness probe command

Source: https://docs.shipyard.build/docker-compose

Sets the command to be executed for the liveness probe as a JSON array.

```yaml
shipyard.liveness.exec.command: '["bash", "some-script.sh"]'
```

--------------------------------

### shipyard rebuild environment

Source: https://docs.shipyard.build/cli

Rebuilds an environment.

```APIDOC
## shipyard rebuild environment {environment_uuid}

### Description
Triggers a rebuild for the specified environment.

### Parameters
#### Path Parameters
- **environment_uuid** (string) - Required - The unique identifier of the environment.
```

--------------------------------

### Environment Management Tools

Source: https://docs.shipyard.build/mcp

Tools for managing the lifecycle and state of Shipyard environments.

```APIDOC
## MCP Tools: Environment Management

- **get_environments**: List environments with filtering
- **get_environment**: Get specific environment details
- **stop_environment**: Stop a running environment
- **restart_environment**: Restart a stopped environment
- **rebuild_environment**: Rebuild with latest commit
- **cancel_environment**: Cancel environment's latest build
- **revive_environment**: Revive a deleted environment
```

--------------------------------

### Configure OAuth callback routes

Source: https://docs.shipyard.build/docker-compose

Specifies callback paths for the Callback Gateway.

```yaml
shipyard.route.oauth.redirect-uri: /callback/oauth/github
```

```yaml
shipyard.route.oauth.google.redirect-uri: /callback/oauth/google
```

--------------------------------

### List Active Environments via cURL

Source: https://docs.shipyard.build/api

Retrieve a list of active environments using query parameters for filtering. Requires the x-api-token header for authentication.

```bash
curl -H 'x-api-token: ${YOUR_API_TOKEN}' "https://shipyard.build/api/v1/environment?pull_request_number=1112&org_name=shipyardbuild"
```

--------------------------------

### shipyard revive environment

Source: https://docs.shipyard.build/cli

Revives a deleted environment.

```APIDOC
## shipyard revive environment {environment_uuid}

### Description
Restores a previously deleted environment.

### Parameters
#### Path Parameters
- **environment_uuid** (string) - Required - The unique identifier of the environment.
```

--------------------------------

### Configure additional host URLs

Source: https://docs.shipyard.build/docker-compose

Exposes additional URLs for a service using JSON configuration strings for prefix, route, and port.

```yaml
shipyard.host.api: '{ "prefix": "api" }'
```

```yaml
shipyard.host.api-with-route: '{ "prefix": "api", "route": "/api/v1" }'
```

```yaml
shipyard.host.api-with-port: '{ "prefix": "api", "port": 9090 }'
```

```yaml
shipyard.host.api-with-route-and-port: '{ "prefix": "api", "route": "/api/v1", "port": 9090 }'
```

--------------------------------

### Configure Codex CLI MCP

Source: https://docs.shipyard.build/mcp

Add the Shipyard MCP server configuration to the Codex CLI config file.

```toml
[mcp_servers.shipyard]  
command = "shipyard"  
args = ["mcp", "serve"]  
env = { "SHIPYARD_API_TOKEN" = "your-token-here", "SHIPYARD_ORG" = "your-org-name" }  
```

--------------------------------

### POST /api/v1/environment/${app_uuid}/cancel

Source: https://docs.shipyard.build/api

Cancels an environment's latest build while it is in progress.

```APIDOC
## POST /api/v1/environment/${app_uuid}/cancel

### Description
Cancels an environment's latest build while it is being built.

### Method
POST

### Endpoint
https://shipyard.build/api/v1/environment/${app_uuid}/cancel

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - The unique identifier of the environment.

### Response
#### Success Response (204)
- Build cancelled successfully
```

--------------------------------

### Define build arguments in .env and Docker Compose

Source: https://docs.shipyard.build/secrets

Set build-time secrets in an .env file and map them to build arguments in the Docker Compose configuration.

```text
APP_ID=124abc
```

```yaml
build:  
  context: .  
  args:  
    - APPLICATION_ID: ${APP_ID}
```

--------------------------------

### Commit and push changes

Source: https://docs.shipyard.build/quickstart

Push your local changes to the main branch to trigger the Shipyard GitOps workflow.

```bash
git add .  
git commit -m "update h1"  
git push origin main  
```

--------------------------------

### Modify application code

Source: https://docs.shipyard.build/quickstart

Update the welcome text in the React frontend to trigger a rebuild.

```javascript
<h1>Hello from k8s :)</h1>  
```

--------------------------------

### Revive an environment via cURL

Source: https://docs.shipyard.build/api

Restores a previously deleted environment.

```bash
curl -H 'x-api-token: ${YOUR_API_TOKEN}' -X POST "https://shipyard.build/api/v1/environment/${app_uuid}/revive"  
```

--------------------------------

### Rebuild an environment

Source: https://docs.shipyard.build/cli

Triggers a rebuild for an environment.

```bash
shipyard rebuild environment {environment_uuid}  
```

--------------------------------

### Output environment variables to terminal

Source: https://docs.shipyard.build/secrets

Use this command to display environment variables matching a specific pattern for batch uploading.

```bash
env | grep 'DEV'
```

--------------------------------

### Restart an environment via cURL

Source: https://docs.shipyard.build/api

Restarts a retired environment using the environment UUID.

```bash
curl -H 'x-api-token: ${YOUR_API_TOKEN}' -X POST "https://shipyard.build/api/v1/environment/${app_uuid}/restart"  
```

--------------------------------

### shipyard exec

Source: https://docs.shipyard.build/cli

Executes a command in a running environment's service.

```APIDOC
## shipyard exec --env {environment_uuid} --service {service_name} -- [command]

### Description
Executes a command within a specific service of a running environment. The container must have a shell available.

### Parameters
#### Query Parameters
- **env** (string) - Required - The unique identifier of the environment.
- **service** (string) - Required - The name of the service.
```

--------------------------------

### Configure primary route

Source: https://docs.shipyard.build/docker-compose

Sets the service URL as the primary environment URL.

```yaml
shipyard.primary-route: true
```

--------------------------------

### Configure multi-repo dependencies

Source: https://docs.shipyard.build/docker-compose

Defines cross-repository service dependencies for multi-repo applications.

```yaml
services:  
  frontend:  
    build: .  
    labels:  
      shipyard.route: '/'  
      shipyard.depends_on: 'api'  
    ports:  
      - 3000:3000
```

```yaml
services:  
  api:  
    build: .  
    labels:  
      shipyard.route: '/api'  
    depends_on:  
      - db  
    ports:  
      - 8080:8080  
  
  db:  
    image: postgres:15
```

```yaml
shipyard.depends_on: 'api,auth-service'
```

--------------------------------

### Define pre-stop command

Source: https://docs.shipyard.build/docker-compose

Executes a command on the Kubernetes pre-stop event, provided as a JSON string.

```yaml
shipyard.lifecycle.preStop.exec.command: "[\"sh\", \"/srv/prestop.sh\"]"  
```

--------------------------------

### shipyard logs

Source: https://docs.shipyard.build/cli

Retrieves logs for a running environment's service.

```APIDOC
## shipyard logs --env {environment_uuid} --service {service_name}

### Description
Fetches logs for a specific service within a running environment.

### Parameters
#### Query Parameters
- **env** (string) - Required - The unique identifier of the environment.
- **service** (string) - Required - The name of the service.
- **follow** (boolean) - Optional - Follow the logs output (default: false).
- **tail** (int) - Optional - Number of recent log lines to show (default: 3000).
```

--------------------------------

### shipyard restart environment

Source: https://docs.shipyard.build/cli

Restarts a stopped environment.

```APIDOC
## shipyard restart environment {environment_uuid}

### Description
Restarts a previously stopped environment. Note: Cancelled environments cannot be restarted and must be rebuilt.

### Parameters
#### Path Parameters
- **environment_uuid** (string) - Required - The unique identifier of the environment.
```

--------------------------------

### Copy file to a service

Source: https://docs.shipyard.build/cli

Appends local file content to a file within a running remote service.

```bash
cat local-file.txt | shipyard exec --env {environment_uuid} --service {service_name} -- bash -c "cat > remote-file.txt"  
```

--------------------------------

### Configure liveness probe period

Source: https://docs.shipyard.build/docker-compose

Sets the interval in seconds between probes.

```yaml
shipyard.liveness.period: 15
```

--------------------------------

### Organization Management Tools

Source: https://docs.shipyard.build/mcp

Tools for managing organization settings.

```APIDOC
## MCP Tools: Organization Management

- **get_orgs**: List all organizations
- **get_org**: Get current default organization
- **set_org**: Set default organization
```

--------------------------------

### Restart an environment

Source: https://docs.shipyard.build/cli

Restarts a previously stopped environment. Note that cancelled environments cannot be restarted and must be rebuilt.

```bash
shipyard restart environment {environment_uuid}  
```

--------------------------------

### Rebuild an environment via cURL

Source: https://docs.shipyard.build/api

Triggers a rebuild for a non-deleted environment.

```bash
curl -H 'x-api-token: ${YOUR_API_TOKEN}' -X POST "https://shipyard.build/api/v1/environment/${app_uuid}/rebuild"  
```

--------------------------------

### Configure liveness probe timeout

Source: https://docs.shipyard.build/docker-compose

Sets the timeout duration in seconds for the probe.

```yaml
shipyard.liveness.timeout_seconds: 10
```

--------------------------------

### Configure Claude Code MCP

Source: https://docs.shipyard.build/mcp

Add the Shipyard MCP server to Claude Code using environment variables or existing CLI configuration.

```bash
claude mcp add shipyard --env SHIPYARD_API_TOKEN=your-token-here --env SHIPYARD_ORG=your-org-name -- shipyard mcp serve  
```

```bash
claude mcp add shipyard -- shipyard mcp serve  
```

--------------------------------

### Configure pod anti-affinity

Source: https://docs.shipyard.build/docker-compose

Encourages replicas within the same deployment to schedule on different nodes.

```yaml
shipyard.remote.podAntiAffinity: true  
```

```yaml
affinity:  
  podAntiAffinity:  
    preferredDuringSchedulingIgnoredDuringExecution:  
    - weight: 75  
      podAffinityTerm:  
        topologyKey: "kubernetes.io/hostname"  
        labelSelector:  
          matchExpressions:  
          - key: component  
            operator: In  
            values:  
            - {{ .deploymentName }}  
```

--------------------------------

### shipyard port-forward

Source: https://docs.shipyard.build/cli

Forwards a service port to localhost.

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

### Description
Forwards a service port from a running environment to a local machine port.

### Parameters
#### Query Parameters
- **env** (string) - Required - The unique identifier of the environment.
- **service** (string) - Required - The name of the service.
- **ports** (string) - Required - The mapping of local port to container port (e.g., 8080:80).
```

--------------------------------

### List environment variables via cURL

Source: https://docs.shipyard.build/api

Retrieves all environment variables for a specified environment.

```bash
curl -H 'x-api-token: ${YOUR_API_TOKEN}' "https://shipyard.build/api/v1/environment/${app_uuid}/env-vars"
```

--------------------------------

### Execute commands in a service

Source: https://docs.shipyard.build/cli

Runs a command inside a service of a running environment. The target container must have a shell available.

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

--------------------------------

### Service Management Tools

Source: https://docs.shipyard.build/mcp

Tools for retrieving information about services within an environment.

```APIDOC
## MCP Tools: Service Management

- **get_services**: List services in an environment
- **get_logs**: Get logs from a service
```

--------------------------------

### POST https://shipyard.build/api/v1/environment/${app_uuid}/stop

Source: https://docs.shipyard.build/api

Stops a currently running environment identified by its UUID.

```APIDOC
## POST https://shipyard.build/api/v1/environment/${app_uuid}/stop

### Description
Stops a currently running environment. Note that you can only stop an environment that is currently running.

### Method
POST

### Endpoint
https://shipyard.build/api/v1/environment/${app_uuid}/stop

### Parameters
#### Path Parameters
- **app_uuid** (string) - Required - The unique identifier of the environment.

### Response
#### Success Response (204)
- Environment stopped successfully.
```

--------------------------------

### Define CircleCI version

Source: https://docs.shipyard.build/circle-ci

Set the required CircleCI version at the top of the configuration file.

```yaml
version: 2.1  
```

--------------------------------

### Port forward a service

Source: https://docs.shipyard.build/cli

Maps a local port to a service port within a running environment.

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

--------------------------------

### Configure environment variables in Docker Compose

Source: https://docs.shipyard.build/secrets

Define environment variables and use string interpolation within a docker-compose.yml file.

```yaml
environment:  
    - STRING_INTERPOLATION=https://${MY_CUSTOM_DOMAIN} # MY_CUSTOM_DOMAIN is defined in Shipyard UI  
    - PREFIX=https://  
    - ENV_VARS_INTERPOLATION=${PREFIX}${MY_CUSTOM_DOMAIN}
```

--------------------------------

### Configure service routing

Source: https://docs.shipyard.build/docker-compose

Defines base routes, path-specific routes, and rewrite behavior for HTTP requests.

```yaml
shipyard.route: '/'
```

```yaml
shipyard.route.api: '/api'
```

```yaml
shipyard.route.rewrite: true
```

--------------------------------

### Configure advanced Kubernetes job labels

Source: https://docs.shipyard.build/docker-compose

Specifies detailed configuration for Kubernetes jobs including restart policies and limits.

```yaml
cronjob:  
    labels:  
      shipyard.job: true  
      shipyard.job.schedule: '*/2 * * * *'  
      shipyard.job.restartPolicy: Never  
      shipyard.job.backoffLimit: 2  
      shipyard.job.activeDeadlineSeconds: 60  
      shipyard.job.successfulJobsHistoryLimit: 5  
      shipyard.job.failedJobsHistoryLimit: 3  
      shipyard.job.concurrencyPolicy: Forbid
```

--------------------------------

### Define security context

Source: https://docs.shipyard.build/docker-compose

Directly defines the Kubernetes security context using a JSON string.

```yaml
shipyard.securityContext: '{"capabilities": {"add": ["SYS_ADMIN"]}}'  
```

--------------------------------

### Configure liveness probe failure threshold

Source: https://docs.shipyard.build/docker-compose

Sets the number of attempts before restarting the container.

```yaml
shipyard.liveness.failure_threshold: 1
```

--------------------------------

### Allocate disk size

Source: https://docs.shipyard.build/docker-compose

Specifies the disk size to be allocated for the volume.

```yaml
shipyard.deploy.disk.size: 10Gi  
```

--------------------------------

### shipyard set org

Source: https://docs.shipyard.build/cli

Sets the global default organization for CLI operations.

```APIDOC
## shipyard set org {org-name}

### Description
Sets the global default organization.

### Parameters
- **org-name** (string) - Required - The name of the organization to set as default.
```

--------------------------------

### shipyard cancel environment

Source: https://docs.shipyard.build/cli

Cancels an ongoing build for an environment.

```APIDOC
## shipyard cancel environment {environment_uuid}

### Description
Cancels an ongoing build process for the specified environment.

### Parameters
#### Path Parameters
- **environment_uuid** (string) - Required - The unique identifier of the environment.
```
Tokens:
Raw