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

# Label

> The formae-side identifier you use to reference a stack or resource.

A `label` is how you identify and reference a stack or resource in formae.
Instead of different terms like "name" or "id" for different technologies,
formae uses `label` consistently throughout the platform.

Resource labels must be unique within a stack, so you can always reference a
specific resource without ambiguity.

## Examples

**A resource label in Pkl:**

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
new bucket.Bucket {
  label = "my-s3-bucket"
  bucketName = "my-unique-bucket-name"
}
```

**A stack label in Pkl:**

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
new formae.Stack {
  label = "my-stack"
  description = "Stack for my resources"
}
```

**Using labels in commands:**

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
# Destroy resources in a specific stack by label
formae destroy --query="stack:production-api"

# View resources with a specific label
formae inventory resources --query="label:my-s3-bucket"
```

<Tip>
  Use descriptive labels that clearly identify the purpose of a stack or
  resource. Labels are how you'll reference and query your infrastructure.
</Tip>

## Labels for discovered resources

When formae discovers a resource that isn't already managed, it assigns a
label so you can refer to it by a readable name rather than the provider's raw
identifier. The label is taken from one of the resource's own properties, so a
discovered resource arrives with a name that already means something to you.

Which property? Each plugin decides, and ships a sensible default. The rule is
expressed as a small [JSONPath](https://www.rfc-editor.org/rfc/rfc9535.html)
query in the plugin's
[`labelConfig`](/documentation/reference/configuration#labelconfig). The syntax
can look dense at first, but it is really just "pull this one field out of the
resource". The AWS plugin's default reads the `Name` tag:

```
$.Tags[?(@.Key=='Name')].Value
```

Read that as: from the resource's `Tags`, take the one whose `Key` is `Name`,
and use its `Value`. So an EC2 instance tagged `Name=web-server` is discovered
with the label `web-server`. You can override the rule per resource type in your
`formae.conf.pkl`.

If the query returns nothing (the resource has no `Name` tag, or your
override matched no fields), formae falls back to the resource's provider
identifier as the label. An EC2 instance with no `Name` tag would be
discovered with a label like `i-0abc1234`.

### Collisions

If two discovered resources would yield the same label, formae appends a
numeric suffix to disambiguate. Three Aurora replica instances all tagged
`Name=database` are discovered as `database`, `database-1`, `database-2`, in
the order they are discovered. The first instance keeps the unsuffixed
label; later ones get the next free number.

Renaming a resource later does not free its old label for future
discoveries: the suffix counter is derived from labels currently in the
inventory, not a separate counter. 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`, not `database`.

## Renaming a resource

Because a label is a formae-side identifier that is never sent to the cloud
provider, you can rename a resource with no cloud operation at all: only the
inventory row changes. This makes labels safe to refactor, and it is how you give
a readable name to a resource that discovery labeled with a raw provider
identifier.

For the steps, see [Rename a resource](/documentation/guides/rename-a-resource).

## See also

* [Resources](/documentation/concepts/resources): managed versus unmanaged resources, and how discovered ones are brought under management.
* [Configuration](/documentation/reference/configuration#labelconfig): overriding a plugin's default label extraction.
* [Resolvable](/documentation/concepts/resolvable): referencing a resource by its label via `.res`.