Amazon Elastic Compute Cloud
CLI Reference (API Version 2012-04-01)
AWS Documentation » Amazon EC2 » Command Line Reference » API Tools Reference » ec2-describe-tags
Print this pageEmail this pageGo to the ForumsView the PDFShare this page on TwitterShare this page on FacebookBookmark this page on DeliciousSubmit this page to RedditSubmit this page to DiggDid this page help you?  Yes  No   Tell us about it...

ec2-describe-tags

Description

Lists your tags. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide.

You can use filters to limit the results when describing tags. For example, you could get only the tags for a particular resource type. You can specify multiple values for a filter. A tag must match at least one of the specified values for it to be included in the results.

You can specify multiple filters (e.g., limit the results to a specific resource type, and get only tags with values that contain the string database). The result includes information for a particular tag only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty.

You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\.

The following table shows the available filters.

Filter Name Description

key

Tag key.

Type: String

resource-id

Resource ID.

Type: String

resource-type

Resource type.

Type: String

Valid Values: customer-gateway | dhcp-options | image | instance | internet-gateway | network-acl | reserved-instances | route-table | security-group | snapshot | spot-instances-request | subnet | volume | vpc | vpn-connection | vpn-gateway

value

Tag value.

Type: String

The short version of this command is ec2dtag.

Syntax

ec2-describe-tags [[--filter name=value] ...]

Options

NameDescriptionRequired

-F, --filter name=value

A filter for limiting the results. See the preceding table for a list of allowed filter names and values. You need to use quotation marks if the value string has a space (e.g., "name=value example"). If you're using the command line tools on a Windows system, you might need to use quotation marks, even when there is no space in the value string (e.g., "name=value").

Type: String

Default: Describes all tags you own, or only those otherwise specified.

Example: --filter "resource-type=instance"

No

Common Options

OptionDescription

--region REGION

Overrides the Region specified in the EC2_URL environment variable and the URL specified by the -U option.

Default: The EC2_URL environment variable, or us-east-1 if the environment variable is not set.

Example: --region eu-west-1

-U, --url URL

URL is the uniform resource locator of the Amazon EC2 web service entry point.

Default: The EC2_URL environment variable, or https://ec2.amazonaws.com if the environment variable is not set.

Example: -U https://ec2.amazonaws.com

-K, --private-key EC2-PRIVATE-KEY

The private key to use when constructing requests to Amazon EC2.

Default: The value of the EC2_PRIVATE_KEY environment variable.

Example: -K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-C, --cert EC2-CERT

The X.509 certificate to use when constructing requests to Amazon EC2.

Default: The value of the EC2_CERT environment variable.

Example: -C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

--connection-timeout TIMEOUT

Specifies a connection timeout (in seconds).

Example: --connection-timeout 30

--request-timeout TIMEOUT

Specifies a request timeout (in seconds).

Example: --request-timeout 45

-v, --verbose

Displays verbose output by showing the SOAP request and response on the command line. This is particularly useful if you are building tools to talk directly to our SOAP API.

-H, --headers

Displays column headers in the output.

--show-empty-fields

Shows empty columns as (nil).

--hide-tags

Do not display tags for tagged resources.

--debug

Prints internal debugging information. This is useful to assist us when troubleshooting problems.

-?, --help, -h

Displays Help.

-

If - is specified as an argument to one of the parameters, a list of arguments is read from standard input. This is useful for piping the output of one command into the input of another.

Example: ec2-describe-instances | grep stopped | cut -f 2 | ec2-start-instances -

Output

The command returns a table that contains the following information:

  • TAG identifier

  • Resource type

  • Resource ID

  • Tag key

  • Tag value

Amazon EC2 command line tools display errors on stderr.

Examples

Example Request

This example describes all the tags belonging to your account.

PROMPT> ec2-describe-tags
TAG  ami-1a2b3c4d  image  webserver
TAG  ami-1a2b3c4d  image  stack  Production
TAG  i-5f4e3d2a  instance  webserver
TAG  i-5f4e3d2a  instance  stack  Production
TAG  i-12345678  instance  database_server
TAG  i-12345678  instance  stack  Test

Example Request

This example describes the tags for the AMI with ID ami-1a2b3c4d.

PROMPT> ec2-describe-tags --filter "resource-id=ami-1a2b3c4d"
TAG  ami-1a2b3c4d  image  webserver
TAG  ami-1a2b3c4d  image  stack  Production

Example Request

This example describes the tags for all your instances.

PROMPT> ec2-describe-tags --filter "resource-type=instance"
TAG  i-5f4e3d2a  instance  webserver
TAG  i-5f4e3d2a  instance  stack  Production
TAG  i-12345678  instance  database_server
TAG  i-12345678  instance  stack  Test

Example Request

This example describes the tags for all your instances tagged with the name webserver.

PROMPT> ec2-describe-tags --filter "resource-type=instance" --filter "key=webserver"
TAG  i-5f4e3d2a  instance  webserver

Example Request

This example describes the tags for all your instances tagged with either stack=Test or stack=Production.

PROMPT> ec2-describe-tags --filter "resource-type=instance" --filter "key=stack" --filter "value=Test" --filter "value=Production"
TAG  i-5f4e3d2a  instance  stack  Production
TAG  i-12345678  instance  stack  Test

Example Request

This example describes the tags for all your instances tagged with Purpose=[empty string].

PROMPT> ec2-describe-tags --filter "resource-type=instance" --filter "key=Purpose" --filter "value="
Document Conventions
Terms of Use		Did this page help you?  Yes  No   Tell us about it...