Namespace tag docs

docs/production-deployment/cloud/get-started/namespaces.mdx

@@ -25,6 +25,7 @@ A Namespace is a unit of isolation within the Temporal Platform.
 - [Access a Namespace](#access-namespaces)
 - [Manage Namespaces](#manage-namespaces)
 - [Delete a Namespace](#delete-a-namespace)
+- [Tag a Namespace](#tag-a-namespace)
 
 ## What is a Cloud Namespace Name? {#temporal-cloud-namespace-name}
 
@@ -376,3 +377,42 @@ tcld namespace lifecycle set \
     --namespace <namespace_id.account_id> \
     --enable-delete-protection <Boolean>
 ```
+
+## How to tag a Namespace in Temporal Cloud {#tag-a-namespace}
+
+:::tip Support, stability, and dependency info
+
+Namespace tags are currently in [Public Preview](/evaluate/development-production-features/release-stages#public-preview).
+
+:::
+
+Tags are key-value metadata pairs that can be attached to namespaces in Temporal Cloud to help operators organize, track, and manage namespaces more easily.
+
+### Tag Structure and Limits
+
+- Each namespace can have a maximum of 10 tags
+- Each key must be unique for a given namespace (e.g., a namespace cannot have both `team:foo` and `team:bar` tags)
+- Keys and values must be 1-63 characters in length
+- Allowed characters: lowercase letters (`a-z`), numbers (`0-9`), periods (`.`), underscores (`_`), and hyphens (`-`)
+- Tags are not a secure storage mechanism and should not store PII or PHI
+- Tags will not change the behavior of the tagged resource
+- There is a soft limit of 1000 unique tag keys per account
+
+### Permissions
+
+- Only [**Account Admins** and **Account Owners**](/cloud/users#account-level-roles) can create and edit tags
+- All users with access to a namespace can view its tags
+
+### tcld
+
+See the [tcld namespace tags](/cloud/tcld/namespace/#tags) command reference for details.
+
+### Terraform
+
+See the [Terraform provider](https://github.com/temporalio/terraform-provider-temporalcloud/) for details.
+
+### Web UI
+
+Tags can be viewed and managed through the Temporal Cloud web interface. When viewing a namespace, you'll see tags displayed and can add, edit, or remove them if you have the appropriate permissions.
+
+

docs/production-deployment/cloud/tcld/namespace.mdx

@@ -33,6 +33,7 @@ Alias: `n`
 - [tcld namespace retention](#retention)
 - [tcld namespace update-codec-server](#update-codec-server)
 - [tcld namespace update-high-availability](#update-high-availability)
+- [tcld namespace tags](#tags)
 
 ## add-region
 
@@ -273,6 +274,14 @@ Include cross-origin credentials (default: false).
 
 Alias: `--ic`
 
+#### --tag
+
+A tag in the form "_key_=_value_".
+
+[Tag structure and limits](/cloud/namespaces#tag-structure-and-limits).
+
+Alias: `--t`
+
 **Example**
 
 ```bash
@@ -286,7 +295,8 @@ tcld namespace create \
     --search-attribute "customer_name=Text" \
     --endpoint "https://test-codec-server.com" \
     --pass-access-token \
-    --include-credentials
+    --include-credentials \
+    --tag "key=value"
 ```
 
 ## delete
@@ -1777,3 +1787,98 @@ tcld --api-key <your_api_key> \
 ```
 
 Alias: `-daf`
+
+## tags
+
+The `tcld namespace tags` commands manage [Tags](/cloud/namespaces#tag-a-namespace) of the specified [Namespace](/namespaces) in Temporal Cloud.
+
+Alias: `t`
+
+- [tcld namespace tags upsert](#upsert)
+- [tcld namespace tags remove](#remove)
+
+### upsert
+
+Add new tags or update existing tag values for the specified Namespace.
+
+Alias: `u`
+
+The following modifier controls the behavior of the command.
+
+#### --namespace
+
+_Required modifier_
+
+Specify a Namespace hosted on Temporal Cloud.
+If not specified, the value of the environment variable $TEMPORAL_CLOUD_NAMESPACE is used.
+
+Alias: `-n`
+
+#### --request-id
+
+The request identifier to use for the asynchronous operation.
+If not set, the server assigns an identifier.
+
+Alias: `-r`
+
+#### --tag
+
+_Required modifier; can be specified more than once_
+
+A tag in the form "_key_=_value_".
+
+[Tag structure and limits](/cloud/namespaces#tag-structure-and-limits).
+
+Alias: `--t`
+
+**Example**
+
+```bash
+tcld namespace tags upsert \
+    --namespace <namespace_id> \
+    --tag "key1=value1" \
+    --tag "key2=updated"
+```
+
+### remove
+
+Remove existing tags for the specified Namespace using the key.
+
+Alias: `rm`
+
+The following modifiers control the behavior of the command.
+
+#### --namespace
+
+_Required modifier_
+
+Specify a Namespace hosted on Temporal Cloud.
+If not specified, the value of the environment variable $TEMPORAL_CLOUD_NAMESPACE is used.
+
+Alias: `-n`
+
+#### --request-id
+
+The request identifier to use for the asynchronous operation.
+If not set, the server assigns an identifier.
+
+Alias: `-r`
+
+#### --tag-key
+
+_Required modifier; can be specified more than once_
+
+A tag key string.
+
+[Tag Key structure and limits](/cloud/namespaces#tag-structure-and-limits).
+
+Alias: `--tk`
+
+**Example**
+
+```bash
+tcld namespace tags remove \
+    --namespace <namespace_id> \
+    --tag-key "key1" \
+    --tag-key "key2"
+```