# Managing things with the registry
You use the AWS IoT console, AWS IoT API, or the AWS CLI to interact with the registry. The following sections show how to use the CLI to work with the registry.
**When naming your thing objects:**
+ Don't use personally identifiable information in your thing name. The thing name can appear in unencrypted communications and reports.
**Topics**
+ [
# Create a thing
](create-thing.md)
+ [
# List things
](list-things.md)
+ [
# Describe things
](search-things.md)
+ [
# Update a thing
](update-thing.md)
+ [
# Delete a thing
](delete-thing.md)
+ [
# Attach a principal to a thing
](attach-thing-principal.md)
+ [
# List things associated with a principal
](list-principal-things.md)
+ [
# List principals associated with a thing
](list-thing-principals.md)
+ [
# List things associated with a principal V2
](list-principal-things-v2.md)
+ [
# List principals associated with a thing V2
](list-thing-principals-v2.md)
+ [
# Detach a principal from a thing
](detach-thing-principal.md)
# Create a thing
The following command shows how to use the AWS IoT **CreateThing** command from the CLI to create a thing. You can't change a thing's name after you create it. To change a thing's name, create a new thing, give it the new name, and then delete the old thing.
```
$ aws iot create-thing \
--thing-type-name "MyLightBulb" \
--attribute-payload "{\"attributes\": {\"wattage\":\"75\", \"model\":\"123\"}}"
```
The **CreateThing** command displays the name and Amazon Resource Name (ARN) of your new thing:
```
{
"thingArn": "arn:aws:iot:us-east-1:123456789012:thing/MyLightBulb",
"thingName": "MyLightBulb",
"thingId": "12345678abcdefgh12345678ijklmnop12345678"
}
```
**Note**
We don't recommend using personally identifiable information in your thing names.
For more information, see [create-thing](https://docs.aws.amazon.com//cli/latest/reference/iot/create-thing.html) from the AWS CLI Command Reference.
# List things
You can use the **ListThings** command to list all things in your account:
```
$ aws iot list-things
```
```
{
"things": [
{
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 1,
"thingName": "MyLightBulb"
},
{
"attributes": {
"numOfStates":"3"
},
"version": 11,
"thingName": "MyWallSwitch"
}
]
}
```
You can use the **ListThings** command to search for all things of a specific thing type:
```
$ aws iot list-things --thing-type-name "LightBulb"
```
```
{
"things": [
{
"thingTypeName": "LightBulb",
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 1,
"thingName": "MyRGBLight"
},
{
"thingTypeName": "LightBulb",
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 1,
"thingName": "MySecondLightBulb"
}
]
}
```
You can use the **ListThings** command to search for all things that have an attribute with a specific value. This command searches up to three attributes.
```
$ aws iot list-things --attribute-name "wattage" --attribute-value "75"
```
```
{
"things": [
{
"thingTypeName": "StopLight",
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 3,
"thingName": "MyLightBulb"
},
{
"thingTypeName": "LightBulb",
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 1,
"thingName": "MyRGBLight"
},
{
"thingTypeName": "LightBulb",
"attributes": {
"model": "123",
"wattage": "75"
},
"version": 1,
"thingName": "MySecondLightBulb"
}
]
}
```
For more information, see [list-things](https://docs.aws.amazon.com//cli/latest/reference/iot/list-things.html) from the AWS CLI Command Reference.
# Describe things
You can use the **DescribeThing** command to display more detailed information about a thing:
```
$ aws iot describe-thing --thing-name "MyLightBulb"
{
"version": 3,
"thingName": "MyLightBulb",
"thingArn": "arn:aws:iot:us-east-1:123456789012:thing/MyLightBulb",
"thingId": "12345678abcdefgh12345678ijklmnop12345678",
"defaultClientId": "MyLightBulb",
"thingTypeName": "StopLight",
"attributes": {
"model": "123",
"wattage": "75"
}
}
```
You can also access this API within the rules engine using the inline function `get_registry_data()`. You can use this function to dynamically access and utilize thing registry information (including attributes, thing types, and group memberships) by calling `DescribeThing` and `ListThingGroupsForThing` APIs directly within AWS IoT rules, enabling real-time message processing and routing based on your device registry data. For more information, see [https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data).
For more information, see [describe-thing](https://docs.aws.amazon.com//cli/latest/reference/iot/describe-thing.html) from the AWS CLI Command Reference.
# Update a thing
You can use the **UpdateThing** command to update a thing. This command updates only the thing's attributes. You can't change a thing's name. To change a thing's name, create a new thing, give it the new name, and then delete the old thing.
```
$ aws iot update-thing --thing-name "MyLightBulb" --attribute-payload "{\"attributes\": {\"wattage\":\"150\", \"model\":\"456\"}}"
```
The **UpdateThing** command does not produce output. You can use the **DescribeThing** command to see the result:
```
$ aws iot describe-thing --thing-name "MyLightBulb"
{
"attributes": {
"model": "456",
"wattage": "150"
},
"version": 2,
"thingName": "MyLightBulb"
}
```
For more information, see [update-thing](https://docs.aws.amazon.com//cli/latest/reference/iot/update-thing.html) from the AWS CLI Command Reference.
# Delete a thing
You can use the **DeleteThing** command to delete a thing:
```
$ aws iot delete-thing --thing-name "MyThing"
```
This command returns successfully with no error if the deletion is successful or you specify a thing that doesn't exist.
For more information, see [delete-thing](https://docs.aws.amazon.com//cli/latest/reference/iot/delete-thing.html) from the AWS CLI Command Reference.
# Attach a principal to a thing
A physical device can use a principal to communicate with AWS IoT. A principal can be an X.509 certificate or an Amazon Cognito ID. You can associate a certificate or an Amazon Cognito ID with the thing in the registry that represents your device, by running the [attach-thing-principal](https://docs.aws.amazon.com//cli/latest/reference/iot/attach-thing-principal.html) command.
To attach a certificate or an Amazon Cognito ID to your thing, use the [attach-thing-principal](https://docs.aws.amazon.com//cli/latest/reference/iot/attach-thing-principal.html) command:
```
$ aws iot attach-thing-principal \
--thing-name "MyLightBulb1" \
--principal "arn:aws:iot:us-east-1:123456789012:cert/a0c01f5835079de0a7514643d68ef8414ab739a1e94ee4162977b02b12842847"
```
To attach a certificate to your thing with an attachment type (exclusive attachment or non-exclusive attachment), use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/attach-thing-principal.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/attach-thing-principal.html) command and specify a type in the `--thing-principal-type` field. An exclusive attachment means your IoT thing is the only thing attached to the certificate, and this certificate cannot be associated with any other things. An non-exclusive attachment means your IoT thing is attached to the certificate, and this certificate can be associated with other things. For more information, see [Associating an AWS IoT thing to an MQTT client connection](exclusive-thing.md).
**Note**
For the [Associating an AWS IoT thing to an MQTT client connection](exclusive-thing.md) feature, you can only use X.509 certificate as a principal.
```
$ aws iot attach-thing-principal \
--thing-name "MyLightBulb2" \
--principal "arn:aws:iot:us-east-1:123456789012:cert/a0c01f5835079de0a7514643d68ef8414ab739a1e94ee4162977b02b12842847" \
--thing-principal-type "EXCLUSIVE_THING"
```
If the attachment is successful, the **AttachThingPrincipal** command does not produce any output. To describe the attachment, use list-thing-principals-v2 CLI command.
For more information, see [AttachThingPrincipal](https://docs.aws.amazon.com//iot/latest/apireference/API_AttachThingPrincipal.html) from the *AWS IoT Core API Reference*.
# List things associated with a principal
To list the things associated with the specified principal, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-principal-things.htmls](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-principal-things.htmls) command. Note that this command doesn't list the attachment type between the thing and the certificate. To list the attachment type, use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-principal-thingsv2.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-principal-thingsv2.html) command. For more information, see [List things associated with a principal V2](list-principal-things-v2.md).
```
$ aws iot list-principal-things \
--principal "arn:aws:iot:us-east-1:123456789012:cert/2e1eb273792174ec2b9bf4e9b37e6c6c692345499506002a35159767055278e8"
```
The output can look like the following.
```
{
"things": [
"MyLightBulb1",
"MyLightBulb2"
]
}
```
For more information, see [ListPrincipalThings](https://docs.aws.amazon.com//iot/latest/apireference/API_ListPrincipalThings.html) from the *AWS IoT Core API Reference*.
# List principals associated with a thing
To list the principals associated with the specified thing, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-thing-principals.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-thing-principals.html) command. Note that this command doesn't list the attachment type between the thing and the certificate. To list the attachment type, use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-thing-principalsv2.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-thing-principalsv2.html) command. For more information, see [List principals associated with a thing V2](list-thing-principals-v2.md).
```
$ aws iot list-thing-principals \
--thing-name "MyLightBulb1"
```
The output can look like the following.
```
{
"principals": [
"arn:aws:iot:us-east-1:123456789012:cert/2e1eb273792174ec2b9bf4e9b37e6c6c692345499506002a35159767055278e8",
"arn:aws:iot:us-east-1:123456789012:cert/1a234b39b4b68278f2e9d84bf97eac2cbf4a1c28b23ea29a44559b9bcf8d395b"
]
}
```
For more information, see [ListThingPrincipals](https://docs.aws.amazon.com//iot/latest/apireference/API_ListThingPrincipals.html) from the *AWS IoT Core API Reference*.
# List things associated with a principal V2
To list the things associated with the specified certificate, along with the attachment type, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-principal-thingsv2.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-principal-thingsv2.html) command. The attachment type refers to how the certificate is attached to the thing.
```
$ aws iot list-principal-things-v2 \
--principal "arn:aws:iot:us-east-1:123456789012:cert/2e1eb273792174ec2b9bf4e9b37e6c6c692345499506002a35159767055278e8"
```
The output can look like the following.
```
{
"PrincipalThingObjects": [
{
"thingPrincipalType": "NON_EXCLUSIVE_THING",
"thing": "arn:aws:iot:us-east-1:123456789012:thing/thing_1"
},
{
"thingPrincipalType": "NON_EXCLUSIVE_THING",
"thing": "arn:aws:iot:us-east-1:123456789012:thing/thing_2"
}
]
}
```
For more information, see [ListPrincipalThingsV2](https://docs.aws.amazon.com//iot/latest/apireference/API_ListPrincipalThingsV2.html) from the *AWS IoT Core API Reference*.
# List principals associated with a thing V2
To list the certificates associated with the specified thing, along with the attachment type, run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-thing-principalsv2.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-thing-principalsv2.html) command. The attachment type refers to how the certificate is attached to the thing.
```
$ aws iot list-thing-principals-v2 \
--thing-name "thing_1"
```
The output can look like the following.
```
{
"ThingPrincipalObjects": [
{
"thingPrincipalType": "NON_EXCLUSIVE_THING",
"principal": "arn:aws:iot:us-east-1:123456789012:cert/2e1eb273792174ec2b9bf4e9b37e6c6c692345499506002a35159767055278e8"
},
{
"thingPrincipalType": "NON_EXCLUSIVE_THING",
"principal": "arn:aws:iot:us-east-1:123456789012:cert/1a234b39b4b68278f2e9d84bf97eac2cbf4a1c28b23ea29a44559b9bcf8d395b"
}
]
}
```
For more information, see [ListThingsPrincipalV2](https://docs.aws.amazon.com//iot/latest/apireference/API_ListThingPrincipalsV2.html) from the *AWS IoT Core API Reference*.
# Detach a principal from a thing
You can use the `DetachThingPrincipal` command to detach a certificate from a thing:
```
$ aws iot detach-thing-principal \
--thing-name "MyLightBulb" \
--principal "arn:aws:iot:us-east-1:123456789012:cert/2e1eb273792174ec2b9bf4e9b37e6c6c692345499506002a35159767055278e8"
```
The **DetachThingPrincipal** command doesn't produce any output.
For more information, see [detach-thing-principal](https://docs.aws.amazon.com//iot/latest/apireference/API_DetachThingPrincipal.html) from the *AWS IoT Core API Reference*.