Formae Rename

---
name: formae-rename
description: "Use when the user wants to rename a managed resource, relabel a resource, change a resource's label, or give a discovery-named resource a readable name — a rename on its own never destroys or recreates the cloud object"
---

# Rename a Resource (`alias`)

Change a resource's `label` without destroying and recreating the cloud object. A rename **on its own** is non-destructive — no cloud operation at all. If you change properties in the same edit, the property change (not the rename) decides the outcome: a mutable change is an in-place update, an immutable (`createOnly`) change forces a destroy-and-recreate `replace`. See "Reading the simulation." The rename happens inline with `apply_forma` — there is no separate rename command.

## How rename works

A `label` is a formae-side identifier; it is never sent to the cloud provider. To rename, set `alias` to the resource's **previous** label and `label` to the **new** one:

```pkl
new vpc.VPC {
  label = "production-vpc"   // the NEW label
  alias = "vpc-008eef..."    // the PREVIOUS label
  cidrBlock = "172.31.0.0/16"
}
```

On apply, the agent matches the existing managed row by `alias` and renames it in place. KSUID and the cloud NativeID are preserved — no destroy/recreate. Cross-resource `.res` references that resolve through the renamed resource's KSUID keep working.

A rename can ride along with a property change in the same apply (one update carries both).

## Workflow

Use `formae-author` to select context and prepare the complete affected stack.
For mode `none`, use its disposable source internally; discuss the old/new
resource labels and actual infrastructure effect, not filenames or alias syntax.
For mode `codebase`, preserve and update the selected maintained project.

1. **Locate the resource in the selected source.** Confirm the current label and the desired new label with the user.
2. **Edit the resource.** Set `alias` to the current label, change `label` to the new name. Leave properties untouched unless the user also asked for a change.
3. **Simulate**: call `apply_forma` with `mode: reconcile` (or `patch`), `simulate: true`.
4. **Check the simulation** against the cases in "Reading the simulation" below. A pure rename is a single `update` with a `change label from "<old>" to "<new>"` line and nothing else. **If the simulation shows a `replace`, stop** — an immutable field changed alongside the rename, and applying will destroy and recreate the cloud object.
5. **Ask for explicit confirmation**, then apply with `simulate: false`.
6. **Monitor** with `get_command_status`:
   - Wait 5 seconds between polls (`sleep 5`). Do NOT poll in a tight loop.
   - Only report state transitions. Summarize what changed rather than dumping JSON.
7. **Report** the renamed resource and command outcome. For a maintained codebase,
   mention the `alias` can stay or be removed (re-applies match the new label first).

## Reading the simulation

The rename itself never destroys the cloud object. What the simulation shows depends on whether you also changed properties in the same edit:

- **Pure rename** — a single `update` whose only change is `change label from "<old>" to "<new>"` (no property patch, no create, no delete). Safe to apply after confirmation.
- **Rename + mutable property change** — an `update` carrying the `change label` line plus a property patch. Still in-place; the cloud object is modified, not recreated. Safe to apply once the user confirms the property change.
- **Rename + immutable (`createOnly`) property change → `replace`** — **DESTRUCTIVE.** The `replace` is driven by the immutable field, not the rename: formae will destroy and recreate the cloud object (losing anything the provider doesn't preserve across recreation). Do NOT treat this as a normal rename outcome. Stop, tell the user plainly that applying will destroy and recreate the resource because of the immutable-field change, and get explicit confirmation — or split the work: do the rename on its own first (non-destructive), then make the property change separately.
- **NOT acceptable — create + delete**: the `alias` doesn't match any existing managed row. Check the alias is the exact current label, same stack, same type. Fix and re-simulate.
- **Apply rejected** with an alias error: see the three pre-flight rejections under "Constraints".

## Constraints

The agent validates `alias` before touching the cloud and rejects:

- **Two resources claim the same row** — one references it by current label, another via `alias`. Remove the duplicate declaration.
- **Dead alias** — `alias` names a label that matches no existing managed (same stack) or unmanaged resource of the same type. Fix or remove it.
- **`alias` equals `label`** — the alias must reference a *different* prior label.

## Renaming while importing

If the resource is still unmanaged (discovered, not yet in a forma), don't use this skill — use `/formae-import` and set `alias` to the discovery-assigned label during the import. The resource is adopted and renamed in one apply.

## Scope

- Renames a resource's `label` only. Moving a resource between stacks or targets is a separate operation.
- Stack rename and target rename are not yet supported.

## Important

- NEVER use `pkl eval` to evaluate forma files — ALWAYS use `formae eval --output-consumer machine`. Forma files use formae-specific extensions that only the formae CLI can resolve, and `--output-consumer machine` ensures parseable output instead of human-formatted text.
- NEVER skip the simulation step
- NEVER apply without user confirmation
- Only set `alias` when the user actually wants a rename — a stray `alias` that matches nothing is rejected at apply time