Skip to main content
Use ryvn update to change a few fields on a resource and leave everything else alone. Use ryvn replace to overwrite a resource with a complete file. Both change resources through the same API as the dashboard, and neither watches a task. To follow what a change started, see Tasks and approvals. For install, authentication, and the other verbs, see CLI.

Choose update or replace

update merges your patch into the current resource. replace treats the file as the whole resource. Anything the file omits can be removed or returned to its default or inherited value, so a partial file can wipe config, env vars, secrets, variable groups, autoscaling, or networking. See Replace a resource.

Read, then patch

Read the current resource first. A patch uses the same field names that get -o yaml prints, so you can copy the shape of the fields you change from that output.
Not every kind can print YAML: Installations and blueprint installations need -e <environment>, because their names are unique only within an environment.

Patch a resource

The patch is JSON or YAML. Send it one of three ways:
Pass -p or --patch-file, not both. A patch is required. Prefer a file for multi-line values such as spec.config, because inline JSON is easy to mangle. Inline patches also land in your shell history and process list, which matters for anything sensitive. Put the fields you change under spec, as get -o yaml shows them. A field at the top level of the patch, such as releaseChannel without spec, is rejected as unknown.

Which kinds update accepts

ryvn update <kind> <name> accepts these kinds: environment, service, and variable-group have their own update subcommands with different rules. See Environments, Services, and Variable groups. The CLI recognizes a few more kinds, such as blueprint, preview, promotion-pipeline, and access-policy, but the server rejects them:
A name the CLI doesn’t know fails before anything is sent, with unknown resource kind and a list of the names it does know. For a kind that update doesn’t accept, save the resource with get -o yaml, edit it, and use replace -f.

Preview a patch

--dry-run merges and validates the patch on the server, prints the merged document, and writes nothing:
--dry-run exists only on ryvn update <kind> <name>. The update environment, update service, and update variable-group subcommands don’t take it.

What update returns

Without --dry-run, update prints one line per changed resource, with the action created, updated, or unchanged, and exits. If the patch fails validation, nothing is written, each error prints as Error: <kind> <name>: <message>, and the exit code is 1. Add -o json for the full result. update doesn’t print a task ID and doesn’t accept --reason, --no-watch, --timeout, or --poll-interval. When the change triggers a deployment, find it with ryvn get installation-task my-app -e production.

How patches merge

A patch is a strategic merge patch. Objects merge field by field. Lists behave in one of two ways, depending on the field. Merged by key. The patch lists only the items you touch. Items you don’t list stay as they are, and an item that already exists is updated in place. Replaced wholesale. The patch value becomes the whole field. Send the complete list or string, because anything you leave out is dropped. Two directives change the defaults:
  • Add $patch: delete to a keyed list item to remove it:
  • Set a field to null to clear it. If that leaves the resource invalid, the patch is rejected and nothing is written.
A keyed list item that omits its key is rejected, for example patch cannot be merged into the ServiceInstallation document: ... does not contain declared merge key: key.

Unknown and protected fields

The server rejects a patch that names a field the kind doesn’t have, so a typo fails instead of being dropped. The error lists every bad path, so you can fix them all in one edit:
When every bad path is at the top level, the error also reminds you to nest the fields under spec:
A patch that writes a protected field is rejected, and nothing is written:
You can’t patch these fields: Other fields aren’t patchable because the kind doesn’t have them. A blueprint installation has no spec.blueprintVersion or spec.autoUpgradeEnabled. Change its version with ryvn set blueprint-version, and turn automatic upgrades off with spec.disableAutoUpgrade: true.

Installations

ryvn update installation my-app -e production accepts the fields in the installation’s YAML, and the merge rules above apply.

Environment variables

spec.env merges by key. Add or change a variable by listing it, and remove one with $patch: delete.

Config

spec.config is a string, and a patch replaces it wholesale. The patch value becomes the entire config. A patch that doesn’t mention spec.config leaves the stored config untouched, including any {{ ... }} template expressions in it. To change one value, read the resource, edit the config in the file, and send the whole resource back:
Or send only the config as a patch, from a file:
The patch value must be the config text itself. The file-reference form, config: [{path: ./values.yaml}], is rejected, because the server can’t read files on your machine:
ryvn create -f, ryvn replace -f, and ryvn plan -f read the local files that config references and include them for you, so the array form works there. See Helm chart installation config.

Secrets

spec.secrets merges by name, and each secret’s values merge by key. A secret has a name and either generated or values. Remove a secret with $patch: delete:
A patch can’t carry a literal secret value. A value field on a secret is rejected as unknown (unknown fields: spec.secrets[0].value). To give an installation a secret value, store it as a sensitive variable in a variable group. Server, job, and Pulumi installations attach the group with spec.variableGroups. Helm chart and Terraform installations can read every variable group in their environment already, and reject spec.variableGroups.

Ports and domains

spec.networking.ports merges by port number, but each port’s domains list is replaced. To change the domains on port 8080, list all of them:

Rollout mode

--rollout-mode synchronous|asynchronous|inherit sets how future deployment tasks wait for rollout readiness. inherit clears the installation’s override and falls back to the service’s setting. Running tasks keep their current mode. Use synchronous if your chart has post-install or post-upgrade hooks that need ready workloads. In asynchronous mode, those hooks run before rollout readiness.
-e is required. --rollout-mode can’t be combined with -p, --patch-file, or --dry-run, and the setting isn’t part of the YAML, so git sync doesn’t manage it.

Blueprint installations

spec.inputs merges by name. Inputs you don’t list keep their values, and $patch: delete drops one:
An input that the installed blueprint version doesn’t declare is stored, and the response warns about it by name. It stays inactive until you install a version that declares it. ryvn set blueprint-input and ryvn unset blueprint-input are shorthand for the same input changes.

Maintenance windows and release channels

A maintenance window’s spec.intervals is replaced wholesale, so send the full list when you change it:

Promotion pipelines

update doesn’t accept promotion-pipeline. A pipeline’s spec.paths is also a single value that any change replaces in full, so work from the whole document: read it, edit the full spec.paths, check it with ryvn plan, and replace it.
For the fields, see Promotion pipelines.

Environments

ryvn update environment <name> is a separate command with its own rules. It takes a patch with -p or --patch-file. It has no -e and no --dry-run.
platform.inputs uses the API input shape, not the shape of the exported resource YAML. To remove a platform input, use ryvn unset blueprint-input <platform-installation> -e <environment> --name <name>.
Changing spec.config or spec.platform.inputs plans an infrastructure change, and the plan waits for approval. An environment that Ryvn has never provisioned gets its first provisioning requested, which also waits for approval. An environment provisioned by an external executor applies the change on the executor’s next run instead. Run ryvn describe environment <name> to find the plan’s task, then review and approve it as described in Tasks and approvals.
Fields that the command doesn’t recognize are ignored when the patch also has a recognized field. A patch with no recognized field fails with no recognized fields in patch — nothing was updated. Unknown keys under spec.platform are rejected, because only inputs is patchable. To change other environment fields, such as maintenanceWindow or namespaces, use ryvn replace -f on the whole environment document. The command applies its steps in order: labels and the other direct fields, then config, then platform inputs. If a later step fails, the earlier ones stay applied. Check the result with ryvn get environment <name> -o yaml.

Services

ryvn update service <name> changes a service’s labels and two settings that live outside its YAML. It can’t change any other service field.
  • metadata.labels replaces all existing labels. An empty object clears them.
  • --rollout-mode synchronous|asynchronous sets the service-level default, and an installation’s own setting overrides it. It applies to future tasks only.
  • --helm-timeout <duration> sets the Helm timeout for a Helm chart service, for example 6h30m. It must be at least one second, and a service of another type is rejected. Tasks that are already running keep their timeout.
A patch with no recognized field and no flag fails with no recognized fields in patch — nothing was updated.

Variable groups

ryvn update variable-group <name> -e <environment> uses its own patch shape, not the resource YAML. A group belongs to one environment, so pass -e.
Keep sensitive values out of -p so they don’t land in your shell history. See Variable groups for revisions and how groups attach to installations.

Rename a resource

A resource’s name is its identity, so a patch can’t change it. The same goes for spec.service, spec.environment, and spec.blueprint on an installation. To rename a Terraform installation without destroying its infrastructure, create a new installation whose spec.renamedFrom names the old one. Don’t delete the old installation first. Deleting runs the destroy task and removes the infrastructure. Start from the old installation’s full document. After seeding, Ryvn applies your file to the new installation, so config, secrets, or variable groups that the file leaves out are removed.
In the file, change metadata.name to the new name and add renamedFrom:
Ryvn seeds the new installation’s Terraform state from the old one, then applies your file to it. If the old installation never provisioned, Ryvn renames it in place. Otherwise the new installation supersedes the old one. The new name must be 45 characters or fewer, use lowercase letters, numbers, and hyphens, start with a lowercase letter, and not end with a dash followed by digits. renamedFrom is a one-time directive that applies only when the new installation is created, and only for Terraform services. The command fails if the old installation isn’t found (renamedFrom source installation "my-old-name" not found in environment production), has been deleted, has already been renamed, or has tasks in progress. Wait for those tasks to finish and try again. In a git-synced repo, remove the old installation’s file in the same commit. You can also rename a standalone Terraform installation from Actions > Rename installation in the dashboard. For any other installation type, or to point an installation at a different service or environment, create the installation you want and delete the old one. Deleting removes the running workload, so plan for the interruption. See Delete installations and environments.

Replace a resource

ryvn replace -f <file> replaces an existing resource from a complete YAML or JSON file. The kind field in the file picks the resource type, and -f - reads stdin. The resource must already exist, or nothing changes. Use ryvn create for a new one. The file replaces the resource in full. Anything it omits is treated as no longer wanted. That can remove current values or restore inherited or default behavior, for example installation config, env vars, secrets, variable groups, autoscaling, networking, lifecycle, or channel settings. So start from the saved resource, edit it, check it, then replace:
For a ServiceInstallation, metadata.name, spec.service, and spec.environment are required, and the namespace can’t change after creation. To change a few settings, use update, ryvn set, or ryvn unset instead. replace also takes -o json. It accepts the array form of spec.config and reads the referenced files from disk, relative to the file that declares them.

Validate before applying

Four checks answer different questions. A typical loop for a file change is lint, then plan, then replace. For a small change, update --dry-run then update.

ryvn lint

ryvn lint validates resource files against the schema without applying anything. With no flags it lints every Ryvn resource file under the current directory. Use -f <file-or-directory> to narrow it, or -f - for stdin.
It validates Blueprint, BlueprintInstallation, Environment, Service, ServiceInstallation, Preview, PromotionPipeline, ReleaseChannel, and MaintenanceWindow files. It checks the file’s shape, so it can’t tell you what a change does to live resources.

ryvn plan

ryvn plan -f <file> shows what applying a file would do, without writing anything. It reports the fields that differ, the externals an apply would invoke, anything that blocks the apply, and a rollup. For a blueprint, it also shows what happens to every service installation under each blueprint installation.
--installation limits a blueprint plan to one blueprint installation. --verbose shows the full config body instead of only the changed hunks. Environment and installation plans compare the declared spec, not resolved runtime state. Each such plan says so in its notices, and resolved config, env, and secret values aren’t compared. A kind that has no planner fails with plan is not yet supported for kind: <kind>. For a CI gate, add --detailed-exitcode:
An incomplete plan exits 2 rather than 0, so a pipeline never treats it as a clean no-op.

ryvn command dry-run

ryvn command dry-run previews a deployment of an installation as it is stored now, optionally at another version: a Helm diff or a Terraform plan, without applying it. Use it after an update to see what the next deployment will do.
It creates a preview task and watches it, like other task-creating commands. --disable-approvals creates a preview that can’t be applied. See Tasks and approvals.

Resources managed by git sync

If git sync manages a resource, a change from the CLI counts as drift. With drift protection on, the next import skips the resource and reports it as drifted. Your change stays in place, but git no longer controls the resource until you resolve the drift. That applies to update and replace alike. To keep the change, export it back to git. To discard it and let git overwrite the resource, resolve the drift:
Settings that ryvn update changes outside the resource YAML, such as --rollout-mode, aren’t part of what git sync manages. See Git sync selectors for the selector forms.