use-ryvn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Use Ryvn

使用Ryvn

Ryvn resource model

Ryvn资源模型

Ryvn organizes infrastructure in a hierarchy:

Organization is the top-level billing and team scope. A user belongs to one or more organizations.
Environment is an isolated infrastructure plane inside an organization (for example,
```
production
```
,
```
staging
```
). Environments are provisioned with cloud infrastructure (GCP).
Service is a deployable unit managed by Ryvn. Services define what can be deployed.
Service Installation (or just "installation") is a deployment of a service into a specific environment. This is the primary unit of deployment.
Blueprint is a template that defines a set of services and their configuration.
Blueprint Installation is an instance of a blueprint deployed to an environment.
Release Channel controls version flows for services.
Promotion Pipeline manages staged releases across environments.
Maintenance Window defines scheduled maintenance periods for an environment.
Connection is an external integration (Infisical for secrets, Temporal for workflows).
Variable Group is a shared configuration group that can be attached to services.
Preview is a PR/feature preview deployment.

Most CLI commands use resource-type shorthand aliases. For example:

env

for environments,

svc

for services,

si

for service-installations,

bp

for blueprints,

bpi

for blueprint-installations,

rc

for release-channels,

pp

for promotion-pipelines,

mw

for maintenance-windows,

conn

for connections,

vg

for variable-groups.

Ryvn 采用层级结构组织基础设施：

Organization：顶级计费与团队范围。一个用户可隶属于一个或多个组织。
Environment：组织内的隔离基础设施平面（例如
```
production
```
、
```
staging
```
）。环境通过云基础设施（GCP）进行配置。
Service：由Ryvn管理的可部署单元。服务定义了可部署的内容。
Service Installation（或简称“installation”）：服务部署到特定环境中的实例。这是部署的基本单元。
Blueprint：定义一组服务及其配置的模板。
Blueprint Installation：部署到环境中的蓝图实例。
Release Channel：控制服务的版本流转。
Promotion Pipeline：管理跨环境的分阶段发布。
Maintenance Window：定义环境的计划维护时段。
Connection：外部集成（如用于密钥管理的Infisical、用于工作流的Temporal）。
Variable Group：可附加到服务的共享配置组。
Preview：PR/功能预览部署。

大多数CLI命令使用资源类型的简写别名。例如：

env

代表环境，

svc

代表服务，

si

代表service-installations，

bp

代表blueprints，

bpi

代表blueprint-installations，

rc

代表release-channels，

pp

代表promotion-pipelines，

mw

代表maintenance-windows，

conn

代表connections，

vg

代表variable-groups。

Preflight

前置检查

Before any mutation, verify context:

bash

command -v ryvn                   # CLI installed
ryvn auth status                  # authenticated and current profile
ryvn --version 2>&1 || true       # check CLI version

If the CLI is missing, guide the user to install it. If not authenticated, run

ryvn auth login

If a profile needs to be switched, use

ryvn auth use profile <name>

. To switch organizations, use

ryvn auth use org <name-or-id>

Environment context: Many commands require

-e <environment>

to specify the target environment. Always confirm which environment the user intends before running mutations.

Global flags available on most commands:

```
--config
```
— config file path
```
--profile
```
— named authentication profile
```
--org
```
— organization override (slug, name, or UUID)
```
--client-id
```
/
```
--client-secret
```
— service account override
```
--debug
```
— debug logging
```
-o json
```
— JSON output for reliable parsing
```
-e
```
/
```
--environment
```
— target environment

执行任何变更操作前，需验证上下文：

bash

command -v ryvn                   # 检查CLI是否已安装
ryvn auth status                  # 检查认证状态及当前配置文件
ryvn --version 2>&1 || true       # 检查CLI版本

若未安装CLI，引导用户进行安装。若未认证，运行

ryvn auth login

。

若需切换配置文件，使用

ryvn auth use profile <name>

。若需切换组织，使用

ryvn auth use org <name-or-id>

。

环境上下文：许多命令需要通过

-e <environment>

指定目标环境。执行变更操作前，务必确认用户的目标环境。

多数命令支持的全局标志：

```
--config
```
— 配置文件路径
```
--profile
```
— 命名认证配置文件
```
--org
```
— 组织覆盖（别名、名称或UUID）
```
--client-id
```
/
```
--client-secret
```
— 服务账号覆盖
```
--debug
```
— 调试日志
```
-o json
```
— 用于可靠解析的JSON输出
```
-e
```
/
```
--environment
```
— 目标环境

Common quick operations

常见快速操作

These are frequent enough to handle without loading a reference:

bash

ryvn get environment                                     # list all environments
ryvn get environment production -o json                  # get specific environment as JSON
ryvn get services                                        # list all services
ryvn get service-installations -e production             # list installations in an environment
ryvn get blueprints                                      # list all blueprints
ryvn get blueprint-installations -e production           # list blueprint installations
ryvn describe environment production                     # detailed environment info
ryvn describe installation my-service -e production      # detailed installation info
ryvn api-resources                                       # list all supported resource types
ryvn logs installations my-service -e production --follow # tail application logs

以下操作频率较高，无需查阅参考文档即可处理：

bash

ryvn get environment                                     # 列出所有环境
ryvn get environment production -o json                  # 以JSON格式获取特定环境信息
ryvn get services                                        # 列出所有服务
ryvn get service-installations -e production             # 列出指定环境中的服务实例
ryvn get blueprints                                      # 列出所有蓝图
ryvn get blueprint-installations -e production           # 列出指定环境中的蓝图实例
ryvn describe environment production                     # 获取环境详细信息
ryvn describe installation my-service -e production      # 获取服务实例详细信息
ryvn api-resources                                       # 列出所有支持的资源类型
ryvn logs installations my-service -e production --follow # 实时查看应用日志

Routing

操作指引

For anything beyond quick operations, load the reference that matches the user's intent. Load only what you need — one reference is usually enough, two at most.

Intent	Reference	Use for
Authenticate, install, or set up profiles	setup.md	Authentication, profiles, service accounts, CLI installation and upgrade
Ship code or manage releases	deploy.md	Environment provisioning/deprovisioning, deploying installations, dry runs, version pinning, task management
Change configuration	configure.md	Environments, services, installations, blueprints, blueprint inputs/exclusions, release channels, promotion pipelines, maintenance windows, connections, variable groups, previews, YAML-based create/replace/update/delete
Check health or debug failures	operate.md	Status, logs, tasks, troubleshooting deployments, monitoring installations

If the request spans two areas (for example, "deploy and then check if it's healthy"), load both references and compose one response.

对于超出快速操作的需求，根据用户意图加载对应的参考文档。仅加载所需内容——通常一个参考文档足够，最多两个。

意图	参考文档	适用场景
认证、安装或配置配置文件	setup.md	认证、配置文件、服务账号、CLI安装与升级
代码发布或版本管理	deploy.md	环境配置/销毁、部署实例、试运行、版本固定、任务管理
变更配置	configure.md	环境、服务、实例、蓝图、蓝图输入/排除项、发布渠道、晋升流水线、维护窗口、连接、变量组、预览、基于YAML的创建/替换/更新/删除操作
健康检查或故障排查	operate.md	状态查看、日志、任务、部署故障排查、实例监控

若用户请求涉及两个领域（例如“部署后检查是否正常”），加载两个参考文档并整合为一个响应。

Execution rules

执行规则

Prefer the Ryvn CLI for all operations.
Use
```
-o json
```
output where available for reliable parsing.
Resolve context before mutation. Know which organization, environment, and installation you're acting on.
For destructive actions (delete installation, deprovision environment), confirm intent and state impact before executing.
After mutations, verify the result with a read-back command (e.g.,
```
ryvn get
```
or
```
ryvn describe
```
).
When deploying installations, prefer
```
--dry-run
```
first if the user hasn't explicitly opted out.
Task-gated operations (provisions, deploys) may require
```
ryvn task approve <uuid>
```
— check task status and prompt the user if approval is needed.

优先使用Ryvn CLI执行所有操作。
尽可能使用
```
-o json
```
输出以确保可靠解析。
执行变更操作前解析上下文。明确当前操作的组织、环境及实例。
对于破坏性操作（删除实例、销毁环境），执行前需确认用户意图及影响范围。
变更操作完成后，通过读取类命令（如
```
ryvn get
```
或
```
ryvn describe
```
）验证结果。
部署实例时，若用户未明确跳过，优先执行
```
--dry-run
```
试运行。
需任务审批的操作（如配置环境、部署）可能需要执行
```
ryvn task approve <uuid>
```
—— 需检查任务状态并在需要时提示用户审批。

Composition patterns

组合工作流模式

Multi-step workflows follow natural chains:

First deploy: setup (authenticate), configure (create environment YAML), deploy (provision environment), configure (create installation YAML), deploy (deploy installation), operate (verify healthy)
Add a service: configure (create service installation YAML), deploy (deploy installation), operate (verify logs)
Blueprint rollout: configure (create blueprint), configure (set blueprint inputs), deploy (deploy installations), operate (verify)
Fix a failure: operate (triage logs and tasks), configure (fix config), deploy (redeploy), operate (verify recovery)
Promote a release: configure (set up promotion pipeline and release channels), deploy (promote across channels)
Preview deployment: configure (create preview), deploy (deploy preview), operate (check preview status)

When composing, return one unified response covering all steps. Don't ask the user to invoke each step separately.

多步骤工作流遵循自然流程：

首次部署：设置（认证）、配置（创建环境YAML）、部署（配置环境）、配置（创建实例YAML）、部署（部署实例）、运维（验证健康状态）
添加服务：配置（创建服务实例YAML）、部署（部署实例）、运维（验证日志）
蓝图推广：配置（创建蓝图）、配置（设置蓝图输入）、部署（部署实例）、运维（验证）
故障修复：运维（排查日志与任务）、配置（修复配置）、部署（重新部署）、运维（验证恢复）
版本晋升：配置（设置晋升流水线与发布渠道）、部署（跨渠道晋升版本）
预览部署：配置（创建预览）、部署（部署预览）、运维（检查预览状态）

整合工作流时，返回包含所有步骤的统一响应，无需让用户单独调用每个步骤。

Response format

响应格式

For all operational responses, return:

What was done (action and scope).
The result (names, status, key output).
What to do next (or confirmation that the task is complete).

Keep output concise. Include command evidence only when it helps the user understand what happened.

所有操作响应需包含：

已执行操作（动作及范围）。
执行结果（名称、状态、关键输出）。
后续操作建议（或任务完成确认）。

保持输出简洁。仅在有助于用户理解过程时包含命令执行证据。