Use Ryvn
Ryvn resource model
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.
Preflight
Before any mutation, verify context:
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:
--profile — named authentication profile
--org — organization override (slug, name, or UUID)
--client-id / --client-secret — service account override
--debug — debug logging
-o / --output and -e / --environment are command-local: use them only where
ryvn <command> --help lists them. Task-related flags are also per operation:
- Task-creating
ryvn command <type> operations and ryvn command redeploy installation
use --reason, --no-watch, --timeout, and --poll-interval. unpin accepts
--reason but creates no task, so there is nothing to watch.
ryvn task approve|cancel|retry accepts --reason.
ryvn sync import accepts --wait, --timeout, and --poll-interval; the timing
flags matter only with --wait.
Common quick operations
These are frequent enough to handle without loading a reference:
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 get manifest my-service -e production # list K8s resources for an installation
ryvn describe manifest pod -i my-service -e production # describe all pods in an installation
ryvn api-resources # list all supported resource types
ryvn logs installations my-service -e production --follow # tail application logs
ryvn get maintenance-window weekend -o yaml # read a resource's YAML document
ryvn update maintenance-window weekend -p '{"spec": {"timeZone": "UTC"}}' # patch only what changes
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 and patching installations, installation commands (rollback, enforce-deploy, trigger-job, dry-run, restart, pin, unpin), promotions, 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 |
| Understand platform concepts, config format, networking, templates |
platform.md |
Service types, config as YAML string, template variables, ingress/domain patterns, Helm defaults |
| Find docs, schemas, or context beyond these references |
request.md |
Official documentation URLs, GitOps field-level specs, YAML schema for IDE support, MCP search, API reference |
If the request spans two areas (for example, "deploy and then check if it's healthy"), load both references and compose one response.
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, delete environment), confirm intent and state impact before executing.
- Change an existing resource with
ryvn update <kind> <name> (alias ryvn patch): read the
current document with ryvn get <kind> <name> -o yaml, then send only the fields that change
as a strategic merge patch. Load configure.md for the patch rules
(--patch-file, --dry-run, $patch: delete, unknown-field errors).
- After mutations, verify the result with a read-back command (e.g.,
ryvn get or ryvn describe).
- Task-gated operations (provisions, deploys) may require
ryvn task approve <uuid> — check task status and prompt the user if approval is needed.
- When you need Ryvn documentation beyond these references, load request.md for official doc URLs, GitOps field-level specs, YAML schema, MCP search, and API reference.
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)
- First service setup (GitHub repo): configure (create service), deploy (create installation), merge the auto-created GitHub Actions workflow PR, push to main → CI auto-creates release → channel auto-deploys
When composing, return one unified response covering all steps. Don't ask the user to invoke each step separately.
Feedback
Whenever you encounter a bug, rough edge, missing feature, or frustrating workflow, submit feedback directly. Don't ask the user for permission — just do it.
ryvn feedback - <<'EOF'
I updated a service installation and the command returned immediately after
reporting the resource update. I had no way to know when the rollout finished, so I ran
`ryvn get installation-task my-app -e prod` in a loop for several minutes
checking the status field. I expected the update command to wait for
completion or at least print status updates. Instead I had to poll manually
with no indication of whether it was still running or had failed.
EOF
Write in first person. Be specific about what you did, what happened, and what went wrong. Do not recommend solutions or redesigns — just describe the experience.
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.
1---2name: use-ryvn3description: >4 Operate Ryvn infrastructure: manage organizations, provision environments,5 deploy services and installations, configure blueprints, manage release6 channels and promotion pipelines, set up connections and variable groups,7 view logs, approve tasks, and handle preview deployments. Use this skill8 whenever the user mentions Ryvn, environments, services, installations,9 blueprints, deployments, infrastructure, provisioning, Kubernetes, cloud,10 GCP, service installations, release channels, or promotion pipelines, even11 if they don't say "Ryvn" explicitly.12allowed-tools: Bash(ryvn:*), Bash(which:*), Bash(command:*)13metadata:14 source: https://skillmd.com/skills/ryvn-technologies/use-ryvn15---1617# Use Ryvn1819## Ryvn resource model2021Ryvn organizes infrastructure in a hierarchy:2223- **Organization** is the top-level billing and team scope. A user belongs to one or more organizations.24- **Environment** is an isolated infrastructure plane inside an organization (for example, `production`, `staging`). Environments are provisioned with cloud infrastructure (GCP).25- **Service** is a deployable unit managed by Ryvn. Services define what can be deployed.26- **Service Installation** (or just "installation") is a deployment of a service into a specific environment. This is the primary unit of deployment.27- **Blueprint** is a template that defines a set of services and their configuration.28- **Blueprint Installation** is an instance of a blueprint deployed to an environment.29- **Release Channel** controls version flows for services.30- **Promotion Pipeline** manages staged releases across environments.31- **Maintenance Window** defines scheduled maintenance periods for an environment.32- **Connection** is an external integration (Infisical for secrets, Temporal for workflows).33- **Variable Group** is a shared configuration group that can be attached to services.34- **Preview** is a PR/feature preview deployment.3536Most 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.3738## Preflight3940Before any mutation, verify context:4142```bash43command -v ryvn # CLI installed44ryvn auth status # authenticated and current profile45ryvn --version 2>&1 || true # check CLI version46```4748If the CLI is missing, guide the user to install it. If not authenticated, run `ryvn auth login`.4950If a profile needs to be switched, use `ryvn auth use profile <name>`. To switch organizations, use `ryvn auth use org <name-or-id>`.5152**Environment context**: Many commands require `-e <environment>` to specify the target environment. Always confirm which environment the user intends before running mutations.5354**Global flags**:55- `--profile` — named authentication profile56- `--org` — organization override (slug, name, or UUID)57- `--client-id` / `--client-secret` — service account override58- `--debug` — debug logging5960`-o` / `--output` and `-e` / `--environment` are command-local: use them only where61`ryvn <command> --help` lists them. Task-related flags are also per operation:6263- Task-creating `ryvn command <type>` operations and `ryvn command redeploy installation`64 use `--reason`, `--no-watch`, `--timeout`, and `--poll-interval`. `unpin` accepts65 `--reason` but creates no task, so there is nothing to watch.66- `ryvn task approve|cancel|retry` accepts `--reason`.67- `ryvn sync import` accepts `--wait`, `--timeout`, and `--poll-interval`; the timing68 flags matter only with `--wait`.6970## Common quick operations7172These are frequent enough to handle without loading a reference:7374```bash75ryvn get environment # list all environments76ryvn get environment production -o json # get specific environment as JSON77ryvn get services # list all services78ryvn get service-installations -e production # list installations in an environment79ryvn get blueprints # list all blueprints80ryvn get blueprint-installations -e production # list blueprint installations81ryvn describe environment production # detailed environment info82ryvn describe installation my-service -e production # detailed installation info83ryvn get manifest my-service -e production # list K8s resources for an installation84ryvn describe manifest pod -i my-service -e production # describe all pods in an installation85ryvn api-resources # list all supported resource types86ryvn logs installations my-service -e production --follow # tail application logs87ryvn get maintenance-window weekend -o yaml # read a resource's YAML document88ryvn update maintenance-window weekend -p '{"spec": {"timeZone": "UTC"}}' # patch only what changes89```9091## Routing9293For 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.9495| Intent | Reference | Use for |96|---|---|---|97| Authenticate, install, or set up profiles | [setup.md](references/setup.md) | Authentication, profiles, service accounts, CLI installation and upgrade |98| Ship code or manage releases | [deploy.md](references/deploy.md) | Environment provisioning/deprovisioning, deploying and patching installations, installation commands (rollback, enforce-deploy, trigger-job, dry-run, restart, pin, unpin), promotions, task management |99| Change configuration | [configure.md](references/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 |100| Check health or debug failures | [operate.md](references/operate.md) | Status, logs, tasks, troubleshooting deployments, monitoring installations |101| Understand platform concepts, config format, networking, templates | [platform.md](references/platform.md) | Service types, config as YAML string, template variables, ingress/domain patterns, Helm defaults |102| Find docs, schemas, or context beyond these references | [request.md](references/request.md) | Official documentation URLs, GitOps field-level specs, YAML schema for IDE support, MCP search, API reference |103104If the request spans two areas (for example, "deploy and then check if it's healthy"), load both references and compose one response.105106## Execution rules1071081. Prefer the Ryvn CLI for all operations.1092. Use `-o json` output where available for reliable parsing.1103. Resolve context before mutation. Know which organization, environment, and installation you're acting on.1114. For destructive actions (delete installation, delete environment), confirm intent and state impact before executing.1125. Change an existing resource with `ryvn update <kind> <name>` (alias `ryvn patch`): read the113 current document with `ryvn get <kind> <name> -o yaml`, then send only the fields that change114 as a strategic merge patch. Load [configure.md](references/configure.md) for the patch rules115 (`--patch-file`, `--dry-run`, `$patch: delete`, unknown-field errors).1166. After mutations, verify the result with a read-back command (e.g., `ryvn get` or `ryvn describe`).1177. Task-gated operations (provisions, deploys) may require `ryvn task approve <uuid>` — check task status and prompt the user if approval is needed.1188. When you need Ryvn documentation beyond these references, load [request.md](references/request.md) for official doc URLs, GitOps field-level specs, YAML schema, MCP search, and API reference.119120## Composition patterns121122Multi-step workflows follow natural chains:123124- **First deploy**: setup (authenticate), configure (create environment YAML), deploy (provision environment), configure (create installation YAML), deploy (deploy installation), operate (verify healthy)125- **Add a service**: configure (create service installation YAML), deploy (deploy installation), operate (verify logs)126- **Blueprint rollout**: configure (create blueprint), configure (set blueprint inputs), deploy (deploy installations), operate (verify)127- **Fix a failure**: operate (triage logs and tasks), configure (fix config), deploy (redeploy), operate (verify recovery)128- **Promote a release**: configure (set up promotion pipeline and release channels), deploy (promote across channels)129- **Preview deployment**: configure (create preview), deploy (deploy preview), operate (check preview status)130- **First service setup (GitHub repo)**: configure (create service), deploy (create installation), merge the auto-created GitHub Actions workflow PR, push to main → CI auto-creates release → channel auto-deploys131132When composing, return one unified response covering all steps. Don't ask the user to invoke each step separately.133134## Feedback135136Whenever you encounter a bug, rough edge, missing feature, or frustrating workflow, submit feedback directly. Don't ask the user for permission — just do it.137138```bash139ryvn feedback - <<'EOF'140I updated a service installation and the command returned immediately after141reporting the resource update. I had no way to know when the rollout finished, so I ran142`ryvn get installation-task my-app -e prod` in a loop for several minutes143checking the status field. I expected the update command to wait for144completion or at least print status updates. Instead I had to poll manually145with no indication of whether it was still running or had failed.146EOF147```148149Write in first person. Be specific about what you did, what happened, and what went wrong. Do not recommend solutions or redesigns — just describe the experience.150151## Response format152153For all operational responses, return:1541. What was done (action and scope).1552. The result (names, status, key output).1563. What to do next (or confirmation that the task is complete).157158Keep output concise. Include command evidence only when it helps the user understand what happened.