> ## Documentation Index
> Fetch the complete documentation index at: https://ryvn.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Updating resources

> Change existing Ryvn resources from the CLI with update and replace, and check the change before you apply it

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](https://ryvn.ai/docs/cli/tasks.md).

For install, authentication, and the other verbs, see [CLI](https://ryvn.ai/docs/cli.md).

## Choose update or replace

| You want to | Use |
| - | - |
| Change one or a few fields, such as an env var, a release channel, or a label | `ryvn update` (alias `ryvn patch`) |
| Make the resource match a file exactly, including removing what the file omits | `ryvn replace -f` |
| Change a field that `update` doesn't accept for that kind | `ryvn replace -f`, starting from the saved resource |

`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](#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.

```bash theme={null}
ryvn get installation my-app -e production -o yaml
ryvn update installation my-app -e production --patch-file patch.yaml
```

Not every kind can print YAML:

| Output | Kinds |
| - | - |
| `-o yaml` and `-o json` | `environment`, `service`, `installation`, `blueprint`, `blueprint-installation`, `release-channel`, `maintenance-window`, `promotion-pipeline`, `preview`, `access-policy` |
| `-o json` only | `variable-group`, `connection` |

Installations and blueprint installations need `-e <environment>`, because their names are unique only within an environment.

## Patch a resource

```bash theme={null}
ryvn update <kind> <name> [-e <environment>] (-p <patch> | --patch-file <file>)
```

The patch is JSON or YAML. Send it one of three ways:

```bash theme={null}
# Inline
ryvn update maintenance-window weekend -p '{"spec": {"timeZone": "UTC"}}'

# From a file
ryvn update maintenance-window weekend --patch-file patch.yaml

# From stdin, using the patch alias and a kind alias
cat patch.yaml | ryvn patch mw weekend --patch-file -
```

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:

| Kind | Aliases | Needs `-e` |
| - | - | - |
| `installation` | `inst`, `si`, `service-installation` | Yes |
| `blueprint-installation` | `bpi` | Yes |
| `maintenance-window` | `mw` | No |
| `release-channel` | `rc` | No |

`environment`, `service`, and `variable-group` have their own `update` subcommands with different rules. See [Environments](#environments), [Services](#services), and [Variable groups](#variable-groups).

The CLI recognizes a few more kinds, such as `blueprint`, `preview`, `promotion-pipeline`, and `access-policy`, but the server rejects them:

```
kind "promotion-pipeline" is not yet enabled for generic patch; enabled kinds: BlueprintInstallation, MaintenanceWindow, ReleaseChannel, ServiceInstallation, Team
```

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`](#replace-a-resource).

### Preview a patch

`--dry-run` merges and validates the patch on the server, prints the merged document, and writes nothing:

```bash theme={null}
ryvn update maintenance-window weekend -p '{"spec": {"timeZone": "UTC"}}' --dry-run
```

`--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.

| List | Item key |
| - | - |
| `spec.env` | `key` |
| `spec.secrets` | `name` |
| `spec.secrets[].values` | `key` |
| `spec.variableGroups` | `name` |
| `spec.inputs` (blueprint installations) | `name` |
| `spec.excludedInstallations` | `name` |
| `spec.networking.ports` | `number` |

**Replaced wholesale.** The patch value becomes the whole field. Send the complete list or string, because anything you leave out is dropped.

| Field | Notes |
| - | - |
| `spec.config` | A string. The patch value replaces the stored config byte for byte. |
| `spec.networking.ports[].domains` | Replaced inside the port that you match by `number`. |
| `spec.dependencies` | `[]` clears all dependencies. |
| `spec.autoscaling.triggers` | The other autoscaling fields still merge. |
| `spec.intervals` (maintenance windows) | |

Two directives change the defaults:

* Add `$patch: delete` to a keyed list item to remove it:

  ```yaml theme={null}
  spec:
    env:
      - key: OLD_VAR
        $patch: delete
  ```

* 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:

```
Error: ServiceInstallation my-app@production: unknown field(s) in patch: spec.autoscalling, spec.envv[0].keyy
```

When every bad path is at the top level, the error also reminds you to nest the fields under `spec`:

```
Error: ServiceInstallation my-app@production: unknown field(s) in patch: releaseChannel; spec fields belong under "spec", as in {"spec": {"releaseChannel": ...}}
```

A patch that writes a protected field is rejected, and nothing is written:

```
Error: ServiceInstallation my-app@production: patch writes to forbidden path "spec.name"
```

You can't patch these fields:

| Applies to | Fields |
| - | - |
| Installation | `spec.name`, `spec.service`, `spec.environment`, `spec.blueprint`, `spec.condition`, `spec.resources`, `spec.renamedFrom` |
| Blueprint installation | `spec.blueprint` |
| Any resource | `kind` and `metadata.name` |

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.

```bash theme={null}
ryvn update installation my-app -e production -p '{"spec": {"releaseChannel": "stable"}}'
```

### Environment variables

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

```yaml theme={null}
# patch.yaml
spec:
  env:
    - key: API_URL
      value: "https://api.example.invalid"
    - key: OLD_VAR
      $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:

```bash theme={null}
ryvn get installation my-app -e production -o yaml > installation.yaml
# edit spec.config in installation.yaml, then:
ryvn replace -f installation.yaml
```

Or send only the config as a patch, from a file:

```yaml theme={null}
# patch.yaml
spec:
  config: |
    replicaCount: 3
    resources:
      limits:
        cpu: "1"
```

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:

```
spec.config file references are not supported over the API: "./values.yaml" is read relative to the resource file in a git checkout, so the server cannot resolve it; send the file contents as a config string instead
```

`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](https://ryvn.ai/docs/iac/installations/helm-chart.md#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`:

```yaml theme={null}
# patch.yaml
spec:
  secrets:
    - name: old-credentials
      $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](https://ryvn.ai/docs/configure/variable-groups.md). 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:

```yaml theme={null}
# patch.yaml
spec:
  networking:
    ports:
      - number: 8080
        domains:
          - app.example.invalid
          - www.example.invalid
```

### 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.

```bash theme={null}
ryvn update installation workers -e staging --rollout-mode asynchronous
```

`-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:

```bash theme={null}
ryvn update blueprint-installation my-stack -e production \
  -p '{"spec": {"inputs": [{"name": "cpu", "value": "2"}]}}'

ryvn update blueprint-installation my-stack -e production \
  -p '{"spec": {"inputs": [{"name": "cpu", "$patch": "delete"}]}}'
```

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

```bash theme={null}
ryvn update release-channel stable -p '{"spec": {"isDefault": true}}'
ryvn update maintenance-window weekend --patch-file patch.yaml
```

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

```yaml theme={null}
# patch.yaml
spec:
  intervals:
    - "Sat 00:00 - Mon 06:00"
```

## 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`](#validate-before-applying), and replace it.

```bash theme={null}
ryvn get promotion-pipeline my-pipeline -o yaml > pipeline.yaml
# edit spec.paths in pipeline.yaml, then:
ryvn plan -f pipeline.yaml
ryvn replace -f pipeline.yaml
```

For the fields, see [Promotion pipelines](https://ryvn.ai/docs/iac/promotion-pipeline.md).

## 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`.

| Field | Effect |
| - | - |
| `spec.displayName` | Sets the display name. |
| `spec.description` | Sets the description. An empty string clears it. |
| `spec.releaseChannel` | Sets the environment's default release channel. |
| `spec.requireApproval` | `true` requires manual approval, `false` auto-approves and overrides the service setting, and `null` inherits the service's `autoApprove`. |
| `spec.config` | Merges into the current environment config, recursively. Nested objects merge, and any other value, including a list, replaces what was there. |
| `spec.platform.inputs` | Sets platform blueprint inputs. Each item is `{name, value}` or `{name, valueFromVariableGroup}`, with exactly one value source. Inputs you don't list are unchanged. |
| `metadata.labels` | Sets labels. |

```bash theme={null}
ryvn update environment production \
  -p '{"spec": {"displayName": "Production", "releaseChannel": "stable"}}'

ryvn update environment production --patch-file patch.yaml
```

```yaml theme={null}
# patch.yaml
spec:
  config:
    region: us-east-1
  platform:
    inputs:
      - name: node_count
        value: 3
```

`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>`.

> [!WARNING]
>
> 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](https://ryvn.ai/docs/cli/tasks.md#review-a-plan-then-approve).

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.

```bash theme={null}
ryvn update service my-api -p '{"metadata": {"labels": {"team": "platform", "tier": "backend"}}}'
ryvn update service my-api -p '{"metadata": {"labels": {}}}'
ryvn update service my-api --rollout-mode synchronous
ryvn update service my-helm-chart --helm-timeout 6h30m
```

* `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`.

| Field | Effect |
| - | - |
| `add` | Variables to add or update. Each has a `key`, a `value`, and optionally `sensitive: true`. |
| `remove` | A list of keys to remove. |
| `description` | Sets the description. An empty string clears it. |

```yaml theme={null}
# variables-patch.yaml
add:
  - key: DB_HOST
    value: postgres.example.invalid
  - key: DB_PASSWORD
    value: replace-me
    sensitive: true
remove:
  - OLD_VAR
```

```bash theme={null}
ryvn update variable-group my-vars -e production --patch-file variables-patch.yaml
```

Keep sensitive values out of `-p` so they don't land in your shell history. See [Variable groups](https://ryvn.ai/docs/configure/variable-groups.md) 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.

```bash theme={null}
ryvn get installation my-old-name -e production -o yaml > renamed-installation.yaml
```

In the file, change `metadata.name` to the new name and add `renamedFrom`:

```yaml theme={null}
# renamed-installation.yaml (excerpt)
kind: ServiceInstallation
metadata:
  name: my-new-name
spec:
  renamedFrom: my-old-name
  # keep the rest of the exported spec, including config and secrets
```

```bash theme={null}
ryvn create -f renamed-installation.yaml
```

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](https://ryvn.ai/docs/cli/tasks.md#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:

```bash theme={null}
ryvn get installation my-app -e production -o yaml > installation.yaml
# edit installation.yaml
ryvn plan -f installation.yaml
ryvn replace -f installation.yaml
```

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.

| Command | Checks | Contacts the server | Changes anything |
| - | - | - | - |
| `ryvn lint` | A file against the resource schema | No | No |
| `ryvn update <kind> <name> --dry-run` | That a patch merges into the live resource and is valid | Yes | No |
| `ryvn plan -f <file>` | What applying a file would change across the live fleet | Yes | No |
| `ryvn command dry-run` | What the next deployment of an installation would do | Yes | Starts a preview task |

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.

```bash theme={null}
ryvn lint
ryvn lint -f environments/production.yaml
```

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.

```bash theme={null}
ryvn plan -f installation.yaml
ryvn plan -f my.blueprint.yaml --installation my-stack-production
ryvn plan -f my.blueprint.yaml --verbose
ryvn plan -f my.blueprint.yaml -o json
```

`--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`:

| Exit code | Meaning |
| - | - |
| 0 | The plan succeeded and has no changes. |
| 1 | An error or a validation failure. |
| 2 | With `--detailed-exitcode` only: the plan contains changes, blocked installations, or installations that failed to plan. |

```bash theme={null}
ryvn plan -f my.blueprint.yaml --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.

```bash theme={null}
ryvn command dry-run -e production -i my-app
ryvn command dry-run -e production -i my-app --version v1.2.3
```

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](https://ryvn.ai/docs/cli/tasks.md).

## Resources managed by git sync

If git sync manages a resource, a change from the CLI counts as drift. With [drift protection](https://ryvn.ai/docs/guides/drift-protection.md) 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:

```bash theme={null}
ryvn sync import --all --resolve-drift installation/my-app -e production --wait
```

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](https://ryvn.ai/docs/cli.md#git-sync-selectors) for the selector forms.

## Related pages

* [Tasks and approvals](https://ryvn.ai/docs/cli/tasks.md): follow, approve, and debug the tasks that a change starts.
* [Drift protection](https://ryvn.ai/docs/guides/drift-protection.md): how git sync treats resources that you change outside git.
* [Variable groups](https://ryvn.ai/docs/configure/variable-groups.md): create groups and attach them to installations.
* [Infrastructure as code](https://ryvn.ai/docs/configure/infrastructure-as-code.md): manage the same resources as YAML in git.
