Shipyard

Shipyard CLI

一个用于在 Shipyard 平台上管理临时环境的工具。

正在使用 AI 助手？CLI 包含一个 MCP 服务器：请参阅 从 AI 助手使用 Shipyard。

安装

• Linux 和 macOS

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

• Windows 导航至 发布页面 并下载适用于 Windows 的可执行文件。

• Homebrew

  brew tap shipyard/tap
  brew install shipyard
  

登录

运行 shipyard login 以初始化 CLI。这将提示您在浏览器中登录 Shipyard。随后 CLI 会将您的 API 令牌保存在本地配置中。您现在可以开始运行命令了。

或手动设置您的令牌

将您的 Shipyard API 令牌设置为 SHIPYARD_API_TOKEN 环境变量的值。

您可以通过访问 您的个人资料页面 获取该令牌。

如果您希望为您的组织启用 API 访问，可以通过 support@shipyard.build 与我们联系。如果您还有其他问题，欢迎加入我们的社区 Slack。

shipyard set token

或者，您可以使用默认存储在 $HOME/.shipyard/config.yaml 中的配置文件。当您首次运行 CLI 时，它会创建一个默认的空配置，您可以随后进行编辑。

您还可以通过在任何命令中添加 --config {path} 标志来指定非默认的配置路径。

在您的配置中添加任何配置值，并确保文件遵循 YAML 语法。例如：

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

您的环境变量的值会覆盖配置中对应的值。

基本用法

获取您所属的所有组织

shipyard get orgs

设置全局默认组织

shipyard set org {org-name}

获取当前配置的组织

shipyard get org

列出所有环境

shipyard get environments

可用标志：

名称	描述	类型	默认值
branch	按分支名称筛选	string
deleted	返回已删除的环境	boolean	false
json	打印完整的 JSON 输出	boolean	false
name	按应用程序名称筛选	string
org-name	按组织名称筛选，如果您属于多个组织	string	您的默认组织
page	请求的页码	int	1
page-size	请求的页面大小	int	20
pull-request-number	按拉取请求编号筛选	string
repo-name	按仓库名称筛选	string

示例：

• 列出在分支 main 上运行仓库 flask-backend 的所有环境：

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

• 列出所有已删除的环境：

shipyard get environments --deleted

通过 UUID 获取特定环境的详细信息

shipyard get environment {environment_uuid}

可用标志：

名称	描述	类型	默认值
json	打印完整的 JSON 输出	boolean	false
org	环境的组织，如果您属于多个组织	string	您的默认组织
bypass-token	仅打印环境的绕过令牌，用于脚本	boolean	false

--bypass-token 允许脚本使用令牌而无需任何人输入或打印它：

SHIPYARD_TOKEN=$(shipyard get environment {environment_uuid} --bypass-token) && \
  export SHIPYARD_TOKEN && curl -b "shipyard_token=$SHIPYARD_TOKEN" https://your-environment-url/

停止正在运行的环境

shipyard stop environment {environment_uuid}

重启已停止的环境

shipyard restart environment {environment_uuid}

取消环境正在进行的构建

shipyard cancel environment {environment_uuid}

重建环境

shipyard rebuild environment {environment_uuid}

恢复已删除的环境

shipyard revive environment {environment_uuid}

部署独立环境

通过克隆现有的应用程序构建来创建一个新的、独立的（"detached"）环境。需要为您的组织启用独立环境。

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

按仓库覆盖分支，并控制独立环境是否在新提交时重建：

# 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

获取环境的所有服务和暴露的端口

shipyard get services --env {environment_uuid}

在正在运行的环境的服务中执行命令

在给定服务中为正在运行的环境执行任何命令及任意参数和标志。在双斜杠后传递任何命令参数。

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

端口转发正在运行的环境的服务的端口

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

获取正在运行的环境的服务的日志

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

访问环境

shipyard visit {environment_uuid}

可用标志：

名称	描述	类型	默认值
follow	跟随日志输出	boolean	false
tail	显示的最近日志行数	int	3000

使用卷

列出环境中的所有卷

shipyard get volumes --env {environment_uuid}

列出环境中的所有卷快照

shipyard get snapshots --env {environment_uuid}

重置环境中的卷

shipyard reset volume --env {environment_uuid}

在环境中创建快照

shipyard create snapshot --env {environment_uuid}

在环境中加载卷快照

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

将文件上传到环境中的卷

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

直接调用 REST API

shipyard api /api/v1/environment
shipyard api -X PUT /api/v1/environment/{environment_uuid}/env-vars --input body.json

路径必须以 /api/v1 或 /api/v2 开头；您的令牌和组织会自动添加。bypass_token 和 kubeconfig 凭据会被编辑掉，除非您传递 --include-secrets。

连接到 telepresence

shipyard telepresence connect --env {environment_uuid}

从那里，您将能够直接与命名空间中的所有 pod 通信。您_可能_需要使用命名空间主机名与服务通信，您可以通过 Namespace 字段下的 telepresence status 获取该主机名。例如，要与 redis 通信，您可以使用 redis.shipyard-app-build-{uuid}

从代码构建可执行文件：

您可以通过运行以下命令来制作可执行文件：

make

要运行这个新的可执行文件：

./shipyard

启用自动补全

Bash

此脚本依赖于 bash-completion 包。如果尚未安装，您可以通过操作系统的包管理器进行安装。 要在当前 shell 会话中加载补全：

source <(shipyard completion bash)

要为每个新会话加载补全，请执行以下操作一次。

在 Linux 上：

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

在 macOS 上：

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

Zsh

如果您的环境中尚未启用 shell 补全，您需要启用它。您可以执行以下操作一次：

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

要在当前 shell 会话中加载补全：

source <(shipyard completion zsh); compdef _shipyard shipyard

要为每个新会话加载补全，请执行以下操作一次。

在 Linux 上：

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

在 macOS 上：

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

您需要启动一个新的 shell 才能使此设置生效。

Fish

要在当前 shell 会话中加载补全：

$ shipyard completion fish | source

要为每个会话加载补全，请执行一次：

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

PowerShell

要在当前 shell 会话中加载补全：

shipyard completion powershell | Out-String | Invoke-Expression

要为每个新会话加载补全，请运行：

shipyard completion powershell > shipyard.ps1

并从您的 PowerShell 配置文件中引用此文件。

从 AI 助手使用 Shipyard（MCP）

shipyard mcp serve 运行一个 模型上下文协议 服务器，因此像 Claude Code、Claude Desktop、Cursor 或 Codex 这样的助手可以列出、检查、重建和配置您的环境，读取服务日志，管理卷，并验证推送的更改与其环境。

在 CLI 登录后，将其添加到 Claude Code：

claude mcp add shipyard -- shipyard mcp serve

然后可以询问类似的问题：

• "哪些环境正在为 web 仓库运行？"
• "显示我分支环境中 api 服务的日志。"
• "在此环境上设置 FEATURE_FLAGS=beta 并重启 worker 服务。"
• "我刚推送了。验证更改与其环境。"（或 /mcp__shipyard__verify）

请参阅 MCP 指南 以了解在其他客户端中的设置、配置、完整工具列表、verify 提示以及故障排除。