**This documentation is for Version 1 of the Amazon CLI only.**

We announced the upcoming end-of-support for the Amazon CLI version 1. We recommend that you migrate to the Amazon CLI version 2. For dates, additional details, and information on how to migrate, see the [announcement](https://amazonaws-china.com/blogs/developer/cli-v1-maintenance-mode-announcement/). For documentation related to Version 2 of the Amazon CLI, see the [Version 2 User Guide](https://docs.amazonaws.cn/cli/latest/userguide/).

# Resource Groups examples using Amazon CLI
<a name="cli_resource-groups_code_examples"></a>

The following code examples show you how to perform actions and implement common scenarios by using the Amazon Command Line Interface with Resource Groups.

*Actions* are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios.

Each example includes a link to the complete source code, where you can find instructions on how to set up and run the code in context.

**Topics**
+ [Actions](#actions)

## Actions
<a name="actions"></a>

### `create-group`
<a name="resource-groups_CreateGroup_cli_topic"></a>

The following code example shows how to use `create-group`.

**Amazon CLI**  
**Example 1: To create a tag-based resource group**  
The following `create-group` example creates a tag-based resource group of Amazon EC2 instances in the current region. It's based on a query for resources that are tagged with the key `Name`, and the value `WebServers`. The group name is `tbq-WebServer`. The query is in a separate JSON file that is passed to the command.  

```
aws resource-groups create-group \
    --name tbq-WebServer \
    --resource-query file://query.json
```
Contents of `query.json`:  

```
{
    "Type": "TAG_FILTERS_1_0",
    "Query": "{\"ResourceTypeFilters\":[\"AWS::EC2::Instance\"],\"TagFilters\":[{\"Key\":\"Name\", \"Values\":[\"WebServers\"]}]}"
}
```
Output:  

```
{
    "Group": {
        "GroupArn": "arn:aws:resource-groups:us-west-2:123456789012:group/tbq-WebServer",
        "Name": "tbq-WebServer"
    },
    "ResourceQuery": {
        "Type": "TAG_FILTERS_1_0",
        "Query": "{\"ResourceTypeFilters\":[\"AWS::EC2::Instance\"],\"TagFilters\":[{\"Key\":\"Name\", \"Values\":[\"WebServers\"]}]}"
    }
}
```
**Example 2: To create a CloudFormation stack-based resource group**  
The following `create-group` example creates an Amazon CloudFormation stack-based resource group named `sampleCFNstackgroup`. The query includes all resources in the specified CloudFormation stack that are supported by Amazon Resource Groups.  

```
aws resource-groups create-group \
    --name cbq-CFNstackgroup \
    --resource-query file://query.json
```
Contents of `query.json`:  

```
{
    "Type": "CLOUDFORMATION_STACK_1_0",
    "Query": "{\"ResourceTypeFilters\":[\"AWS::AllSupported\"],\"StackIdentifier\":\"arn:aws:cloudformation:us-west-2:123456789012:stack/MyCFNStack/1415z9z0-z39z-11z8-97z5-500z212zz6fz\"}"
}
```
Output:  

```
{
    "Group": {
        "GroupArn": "arn:aws:resource-groups:us-west-2:123456789012:group/cbq-CFNstackgroup",
        "Name": "cbq-CFNstackgroup"
    },
    "ResourceQuery": {
        "Type": "CLOUDFORMATION_STACK_1_0",
        "Query": "{\"ResourceTypeFilters\":[\"AWS::AllSupported\"],\"StackIdentifier\":\"arn:aws:cloudformation:us-east-2:123456789012:stack/MyCFNStack/1415z9z0-z39z-11z8-97z5-500z212zz6fz\"}"}'
    }
}
```
For more information, see [Create Groups](https://docs.aws.amazon.com/ARG/latest/userguide/gettingstarted-query.html) in the *Amazon Resource Groups User Guide*.  
+  For API details, see [CreateGroup](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/resource-groups/create-group.html) in *Amazon CLI Command Reference*. 

### `delete-group`
<a name="resource-groups_DeleteGroup_cli_topic"></a>

The following code example shows how to use `delete-group`.

**Amazon CLI**  
**To update the description for a resource group**  
The following `delete-group` example updates the specified resource group.  

```
aws resource-groups delete-group \
    --group-name tbq-WebServer
```
Output:  

```
{
    "Group": {
        "GroupArn": "arn:aws:resource-groups:us-west-2:1234567890:group/tbq-WebServer",
        "Name": "tbq-WebServer"
    }
}
```
For more information, see [Delete Groups](https://docs.aws.amazon.com/ARG/latest/userguide/deleting-resource-groups.html) in the *Amazon Resource Groups User Guide*.  
+  For API details, see [DeleteGroup](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/resource-groups/delete-group.html) in *Amazon CLI Command Reference*. 

### `get-group-query`
<a name="resource-groups_GetGroupQuery_cli_topic"></a>

The following code example shows how to use `get-group-query`.

**Amazon CLI**  
**To get the query attached to a resource group**  
The following `get-group-query` example displays query attached to the specified resource group.  

```
aws resource-groups get-group-query \
    --group-name tbq-WebServer
```
Output:  

```
{
    "GroupQuery": {
        "GroupName": "tbq-WebServer",
        "ResourceQuery": {
            "Type": "TAG_FILTERS_1_0",
            "Query": "{\"ResourceTypeFilters\":[\"AWS::EC2::Instance\"],\"TagFilters\":[{\"Key\":\"Name\", \"Values\":[\"WebServers\"]}]}"
        }
    }
}
```
+  For API details, see [GetGroupQuery](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/resource-groups/get-group-query.html) in *Amazon CLI Command Reference*. 

### `get-group`
<a name="resource-groups_GetGroup_cli_topic"></a>

The following code example shows how to use `get-group`.

**Amazon CLI**  
**To get information about a resource group**  
The following `get-group` example displays details about the specified resource group. To get the query attached to the group, use `get-group-query`.  

```
aws resource-groups get-group \
    --group-name tbq-WebServer
```
Output:  

```
{
    "Group": {
        "GroupArn": "arn:aws:resource-groups:us-west-2:123456789012:group/tbq-WebServer",
        "Name": "tbq-WebServer",
        "Description": "A tag-based query resource group of WebServers."
    }
}
```
+  For API details, see [GetGroup](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/resource-groups/get-group.html) in *Amazon CLI Command Reference*. 

### `get-tags`
<a name="resource-groups_GetTags_cli_topic"></a>

The following code example shows how to use `get-tags`.

**Amazon CLI**  
**To retrieve the tags attached to a resource group**  
The following `get-tags` example displays the tag key and value pairs attached to the specified resource group (the group itself, not its members).  

```
aws resource-groups get-tags \
    --arn arn:aws:resource-groups:us-west-2:123456789012:group/tbq-WebServer
```
Output:  

```
{
    "Arn": "arn:aws:resource-groups:us-west-2:123456789012:group/tbq-WebServer",
    "Tags": {
        "QueryType": "tags",
        "QueryResources": "ec2-instances"
    }
}
```
+  For API details, see [GetTags](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/resource-groups/get-tags.html) in *Amazon CLI Command Reference*. 

### `list-group-resources`
<a name="resource-groups_ListGroupResources_cli_topic"></a>

The following code example shows how to use `list-group-resources`.

**Amazon CLI**  
**To list all of the resources in a resource group**  
Example 1: The following `list-resource-groups` example lists all of the resources that are part of the specified resource group.  

```
aws resource-groups list-group-resources \
    --group-name tbq-WebServer
```
Output:  

```
{
    "ResourceIdentifiers": [
        {
            "ResourceArn": "arn:aws:ec2:us-west-2:123456789012:instance/i-09f77fa38c12345ab",
            "ResourceType": "AWS::EC2::Instance"
        }
    ]
}
```
Example 2: The following example lists all of the resources in the group that also have a 'resource-type' of the 'Amazon::EC2::Instance'. :  
aws resource-groups list-group-resources --group-name tbq-WebServer --filters Name=resource-type,Values=Amazon::EC2::Instance  
+  For API details, see [ListGroupResources](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/resource-groups/list-group-resources.html) in *Amazon CLI Command Reference*. 

### `list-groups`
<a name="resource-groups_ListGroups_cli_topic"></a>

The following code example shows how to use `list-groups`.

**Amazon CLI**  
**To list the available resource groups**  
The following `list-groups` example displays a list of all of the resource groups.  

```
aws resource-groups list-groups
```
Output:  

```
{
    "GroupIdentifiers": [
        {
            "GroupName": "tbq-WebServer",
            "GroupArn": "arn:aws:resource-groups:us-west-2:123456789012:group/tbq-WebServer3"
        },
        {
            "GroupName": "cbq-CFNStackQuery",
            "GroupArn": "arn:aws:resource-groups:us-west-2:123456789012:group/cbq-CFNStackQuery"
        }
    ],
    "Groups": [
        {
            "GroupArn": "arn:aws:resource-groups:us-west-2:123456789012:group/tbq-WebServer",
            "Name": "tbq-WebServer"
        },
        {
            "GroupArn": "arn:aws:resource-groups:us-west-2:123456789012:group/cbq-CFNStackQuery",
            "Name": "cbq-CFNStackQuery"
        }
    ]
}
```
+  For API details, see [ListGroups](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/resource-groups/list-groups.html) in *Amazon CLI Command Reference*. 

### `list-resource-groups`
<a name="resource-groups_ListResourceGroups_cli_topic"></a>

The following code example shows how to use `list-resource-groups`.

**Amazon CLI**  
**To list all of the resources in a resource group**  
The following `list-resource-groups` example lists all of the resources that are part of the specified resource group.  

```
aws resource-groups list-group-resources \
    --group-name tbq-WebServer
```
Output:  

```
{
    "ResourceIdentifiers": [
        {
            "ResourceArn": "arn:aws:ec2:us-west-2:123456789012:instance/i-09f77fa38c12345ab",
            "ResourceType": "AWS::EC2::Instance"
        }
    ]
}
```
+  For API details, see [ListResourceGroups](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/resource-groups/list-resource-groups.html) in *Amazon CLI Command Reference*. 

### `put-group-configuration`
<a name="resource-groups_PutGroupConfiguration_cli_topic"></a>

The following code example shows how to use `put-group-configuration`.

**Amazon CLI**  
**To attach a service configuration to a resource group**  
Example 1: The following `put-group-configuration` example specifies that the resource group is to contain only Amazon EC2 capacity reservations for instances in the `C5` or `M5` families.  

```
aws resource-groups put-group-configuration \
    --group MyTestGroup \
    --configuration file://config.json
```
Contents of `config.json`:  

```
[
    {
        "Type": "AWS::EC2::HostManagement",
        "Parameters": [
            {
                "Name": "allowed-host-families",
                "Values": [ "c5", "m5" ]
            },
                {
                    "Name": "any-host-based-license-configuration",
                    "Values": [ "true" ]
                }
        ]
    },
    {
        "Type": "AWS::ResourceGroups::Generic",
        "Parameters": [
            {
                "Name": "allowed-resource-types",
                "Values": [ "AWS::EC2::Host" ]
            },
            {
                "Name": "deletion-protection",
                "Values": [ "UNLESS_EMPTY" ]
            }
        ]
    }
]
```
This command produces no output if successful.  
For more information, see [Service configurations for resource groups](https://docs.aws.amazon.com/ARG/latest/APIReference/about-slg.html) in the *Resource Groups API Reference Guide*.  
+  For API details, see [PutGroupConfiguration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/resource-groups/put-group-configuration.html) in *Amazon CLI Command Reference*. 

### `search-resources`
<a name="resource-groups_SearchResources_cli_topic"></a>

The following code example shows how to use `search-resources`.

**Amazon CLI**  
**To find resources that match a query**  
The following `search-resources` example retrieves a list of all Amazon resources that match the specified query.  

```
aws resource-groups search-resources \
    --resource-query file://query.json
```
Contents of `query.json`:  

```
{
    "Type": "TAG_FILTERS_1_0",
    "Query": "{\"ResourceTypeFilters\":[\"AWS::EC2::Instance\"],\"TagFilters\":[{\"Key\":\"Patch Group\", \"Values\":[\"Dev\"]}]}"
}
```
Output:  

```
{
    "ResourceIdentifiers": [
        {
            "ResourceArn": "arn:aws:ec2:us-west-2:123456789012:instance/i-01a23bc45d67890ef",
            "ResourceType": "AWS::EC2::Instance"
        }
    ]
}
```
+  For API details, see [SearchResources](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/resource-groups/search-resources.html) in *Amazon CLI Command Reference*. 

### `tag`
<a name="resource-groups_Tag_cli_topic"></a>

The following code example shows how to use `tag`.

**Amazon CLI**  
**To attach a tag to a resource group**  
The following `tag` example attaches the specified tag key and value pairs to the specified resource group (the group itself, not its members).  

```
aws resource-groups tag \
    --tags QueryType=tags,QueryResources=ec2-instances \
    --arn arn:aws:resource-groups:us-west-2:128716708097:group/tbq-WebServer
```
Output:  

```
{
    "Arn": "arn:aws:resource-groups:us-west-2:128716708097:group/tbq-WebServer",
    "Tags": {
        "QueryType": "tags",
        "QueryResources": "ec2-instances"
    }
}
```
For more information, see [Manage tags](https://docs.aws.amazon.com/ARG/latest/userguide/tagging-resources.html) in the *Amazon Resource Groups User Guide*.  
+  For API details, see [Tag](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/resource-groups/tag.html) in *Amazon CLI Command Reference*. 

### `untag`
<a name="resource-groups_Untag_cli_topic"></a>

The following code example shows how to use `untag`.

**Amazon CLI**  
**To remove tags from a resource group**  
The following `untags` example removes any tag with the specified key from the resource group itself, not its members.  

```
aws resource-groups untag \
    --arn arn:aws:resource-groups:us-west-2:123456789012:group/tbq-WebServer \
    --keys QueryType
```
Output:  

```
{
    "Arn": "arn:aws:resource-groups:us-west-2:123456789012:group/tbq-WebServer",
    "Keys": [
        "QueryType"
    ]
}
```
For more information, see [Manage tags](https://docs.aws.amazon.com/ARG/latest/userguide/tagging-resources.html) in the *Amazon Resource Groups User Guide*.  
+  For API details, see [Untag](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/resource-groups/untag.html) in *Amazon CLI Command Reference*. 

### `update-group-query`
<a name="resource-groups_UpdateGroupQuery_cli_topic"></a>

The following code example shows how to use `update-group-query`.

**Amazon CLI**  
**Example 1: To update the query for a tag-based resource group**  
The following `update-group-query` example updates the query attached to the specified tag-based resource group.  

```
aws resource-groups update-group-query \
    --group-name tbq-WebServer \
    --resource-query '{"Type":"TAG_FILTERS_1_0", "Query":"{\"ResourceTypeFilters\":[\"AWS::EC2::Instance\"],\"TagFilters\":[{\"Key\":\"Name\", \"Values\":[\"WebServers\"]}]}"}'
```
Output:  

```
{
    "Group": {
        "GroupArn": "arn:aws:resource-groups:us-east-2:123456789012:group/tbq-WebServer",
        "Name": "tbq-WebServer"
    },
    "ResourceQuery": {
        "Type": "TAG_FILTERS_1_0",
        "Query": "{\"ResourceTypeFilters\":[\"AWS::EC2::Instance\"],\"TagFilters\":[{\"Key\":\"Name\", \"Values\":[\"WebServers\"]}]}"
    }
}
```
For more information, see [Update Groups](https://docs.aws.amazon.com/ARG/latest/userguide/updating-resource-groups.html) in the *Amazon Resource Groups User Guide*.  
**Example 2: To update the query for a CloudFormation stack-based resource group**  
The following `update-group-query` example updates the query attached to the specified Amazon CloudFormation stack-based resource group.  

```
aws resource-groups update-group-query \
    --group-name cbq-CFNstackgroup \
    --resource-query '{"Type": "CLOUDFORMATION_STACK_1_0", "Query": "{\"ResourceTypeFilters\":[\"AWS::AllSupported\"],\"StackIdentifier\":\"arn:aws:cloudformation:us-west-2:123456789012:stack/MyCFNStack/1415z9z0-z39z-11z8-97z5-500z212zz6fz\"}"}'
```
Output:  

```
{
    "Group": {
        "GroupArn": "arn:aws:resource-groups:us-west-2:123456789012:group/cbq-CFNstackgroup",
        "Name": "cbq-CFNstackgroup"
    },
    "ResourceQuery": {
        "Type": "CLOUDFORMATION_STACK_1_0",
        "Query": "{\"ResourceTypeFilters\":[\"AWS::AllSupported\"],\"StackIdentifier\":\"arn:aws:cloudformation:us-west-2:123456789012:stack/MyCFNStack/1415z9z0-z39z-11z8-97z5-500z212zz6fz\"}"
    }
}
```
For more information, see [Update Groups](https://docs.aws.amazon.com/ARG/latest/userguide/updating-resource-groups.html) in the *Amazon Resource Groups User Guide*.  
+  For API details, see [UpdateGroupQuery](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/resource-groups/update-group-query.html) in *Amazon CLI Command Reference*. 

### `update-group`
<a name="resource-groups_UpdateGroup_cli_topic"></a>

The following code example shows how to use `update-group`.

**Amazon CLI**  
**To update the description for a resource group**  
The following `update-group` example updates the description for the specified resource group.  

```
aws resource-groups update-group \
    --group-name tbq-WebServer \
    --description "Resource group for all web server resources."
```
Output:  

```
{
    "Group": {
        "GroupArn": "arn:aws:resource-groups:us-west-2:123456789012:group/tbq-WebServer",
        "Name": "tbq-WebServer"
        "Description": "Resource group for all web server resources."
    }
}
```
For more information, see [Update Groups](https://docs.aws.amazon.com/ARG/latest/userguide/updating-resource-groups.html) in the *Amazon Resource Groups User Guide*.  
+  For API details, see [UpdateGroup](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/resource-groups/update-group.html) in *Amazon CLI Command Reference*.