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

# Rename a resource

> Change a managed resource's label without recreating the cloud object, using alias.

A [label](/documentation/concepts/label) is a formae-side identifier that lives in
formae's inventory and is never sent to the cloud provider. formae tracks each
resource by an internal id, so changing a label is a metadata update: the
inventory row changes and the cloud object stays exactly as it is.

To rename, set the resource's `alias` to its current label and its `label` to the
new one, then apply. formae matches the resource by its `alias` and updates the
label in place. This works in both reconcile and patch mode.

<Tabs>
  <Tab title="CLI">
    <Steps>
      <Step title="Set alias and the new label">
        In the forma where the resource is declared, add `alias` with its current
        label and change `label` to the new one:

        ```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
        new bucket.Bucket {
          label = "lambda-artifacts"           // the new label
          alias = "artifacts-bucket-cdk"       // its current label
          bucketName = "acme-lambda-artifacts"
        }
        ```
      </Step>

      <Step title="Apply">
        ```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
        formae apply --mode reconcile my-forma.pkl
        ```

        The plan is a single label change with no cloud operations: formae renames
        the inventory row and leaves the resource untouched. You can drop the
        `alias` afterwards, or leave it in place, a later apply with the alias
        still set is a no-op.

        Confirm and formae completes the rename in place, with no cloud call:

        <div className="fa-term">
          <div className="fa-term-body">  <span style={{fontWeight:'600'}} /><span style={{color:'rgb(232,232,232)',fontWeight:'600'}}>formae</span> <span style={{fontWeight:'600'}} /><span style={{color:'rgb(255,133,51)',fontWeight:'600'}}>status command</span>                                                                                     <span style={{color:'rgb(129,209,219)'}}>↻ live</span><br /><span style={{color:'rgb(85,85,102)'}}>────────────────────────────────────────────────────────────────────────────────────────────────────────────────────</span><br /><span style={{color:'rgb(85,85,102)'}} /><span style={{color:'rgb(85,85,102)',fontWeight:'600'}} /><span style={{color:'rgb(170,170,170)',fontWeight:'600'}}>     ID                          Command   Mode        Progress                         ✓    ✗    ◐    ○    Time</span><br /><span style={{color:'rgb(170,170,170)',fontWeight:'600'}} /><span style={{color:'rgb(232,232,232)'}}>✓    </span><span style={{color:'rgb(129,209,219)'}}>3GprjIv3mF4CxosYjVhW5dbSUhi </span><span style={{color:'rgb(232,232,232)'}}>apply     reconcile   completed 1/1                    1    0    0    0    00:00</span><br /><span style={{color:'rgb(232,232,232)'}} /><span style={{color:'rgb(85,85,102)'}}>────────────────────────────────────────────────────────────────────────────────────────────────────────────────────</span><br /><span style={{color:'rgb(85,85,102)'}} /><br /><span style={{color:'rgb(85,85,102)'}}>  </span><span style={{color:'rgb(85,85,102)',fontWeight:'600'}} /><span style={{color:'rgb(255,133,51)',fontWeight:'600'}}>▌ Resources</span><br />  <span style={{color:'rgb(170,170,170)'}}>      </span><span style={{color:'rgb(170,170,170)',fontWeight:'600'}} /><span style={{color:'rgb(232,232,232)',fontWeight:'600'}} /><span style={{color:'rgb(232,232,232)',fontWeight:'600'}}>Label ▲                                               </span><span style={{color:'rgb(170,170,170)'}}>Type                                Operation   Time</span><br />   <span style={{color:'rgb(232,232,232)'}} /><span style={{color:'rgb(232,232,232)'}}>✓</span>    <span style={{color:'rgb(170,170,170)'}}>lambda-artifacts</span>                                      <span style={{color:'rgb(170,170,170)'}}>AWS::S3::Bucket</span>                     <span style={{color:'rgb(170,170,170)'}}>update</span>      <span style={{color:'rgb(170,170,170)'}}>00:00</span><br /><br /><span style={{color:'rgb(85,85,102)'}}>────────────────────────────────────────────────────────────────────────────────────────────────────────────────────</span><br /><span style={{color:'rgb(85,85,102)'}} />  <span style={{fontWeight:'600'}} /><span style={{color:'rgb(129,209,219)',fontWeight:'600'}}>→←</span><span style={{color:'rgb(153,153,153)'}}>: column</span>  <span style={{fontWeight:'600'}} /><span style={{color:'rgb(129,209,219)',fontWeight:'600'}}>s</span><span style={{color:'rgb(153,153,153)'}}>: toggle sort</span>  <span style={{fontWeight:'600'}} /><span style={{color:'rgb(129,209,219)',fontWeight:'600'}}>space</span><span style={{color:'rgb(153,153,153)'}}>: expand</span>  <span style={{fontWeight:'600'}} /><span style={{color:'rgb(129,209,219)',fontWeight:'600'}}>d</span><span style={{color:'rgb(153,153,153)'}}>: details</span>  <span style={{fontWeight:'600'}} /><span style={{color:'rgb(129,209,219)',fontWeight:'600'}}>esc</span><span style={{color:'rgb(153,153,153)'}}>: back</span>  <span style={{fontWeight:'600'}} /><span style={{color:'rgb(129,209,219)',fontWeight:'600'}}>q</span><span style={{color:'rgb(153,153,153)'}}>: quit</span>                                <span style={{fontWeight:'600'}} /><span style={{color:'rgb(129,209,219)',fontWeight:'600'}}>?</span><span style={{color:'rgb(153,153,153)'}}>: help</span></div>
        </div>
      </Step>
    </Steps>
  </Tab>

  <Tab title="AI assistants">
    With the [formae MCP plugin](/documentation/guides/ai-coding-assistants)
    connected, ask for the rename and let the assistant set the `alias` for you:

    <div className="fa-convo">
      <div className="fa-convo-head">Conversation</div>
      <div className="fa-turn fa-you"><div className="fa-tag">You</div><div className="fa-body">Rename the bucket artifacts-bucket-cdk to lambda-artifacts.</div></div>
      <div className="fa-turn fa-bot"><div className="fa-tag">Assistant</div><div className="fa-body">I'll set its alias to the current label and change the label, then simulate first: the plan changes the label from <code>artifacts-bucket-cdk</code> to <code>lambda-artifacts</code> on the S3 bucket in <code>web-backend</code>, with no change to the bucket itself. Apply it?</div></div>
      <div className="fa-turn fa-you"><div className="fa-tag">You</div><div className="fa-body">Yes.</div></div>
      <div className="fa-turn fa-bot"><div className="fa-tag">Assistant</div><div className="fa-body">Renamed. It's now <code>lambda-artifacts</code>, and the bucket itself was untouched.</div></div>
    </div>
  </Tab>
</Tabs>

## Naming a discovered resource

When [discovery](/documentation/concepts/discovery) labels a resource with a raw
provider id (a VPC discovered as `vpc-008eef40942ac586b`, say), give it a readable
name as you bring it under management: set `alias` to the discovered label and
`label` to the name you want.

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
new vpc.VPC {
  label = "production-vpc"
  alias = "vpc-008eef40942ac586b"
  cidrBlock = "172.31.0.0/16"
}
```

<Note>
  Renaming does not free the old label for future discoveries. The numeric suffix
  that [disambiguates discovered labels](/documentation/concepts/label) advances
  past whatever is already in the inventory, so renaming `database` to
  `aurora-writer` while `database-1` and `database-2` still exist means the next
  discovery that would land on `database` becomes `database-3`.
</Note>

## See also

* [Label](/documentation/concepts/label): what a label is and how discovered resources get one.
* [Bring existing resources under management](/documentation/guides/bring-resources-under-management): adopt discovered resources, often renaming them in the process.
* [Apply modes](/documentation/concepts/apply-modes): reconcile and patch both support renaming.