AWS command reference

CloudTrail CLI

Cheat Sheet

Cybr

Christophe Limpalair ↗ @christophelimp ↗

General / Operational

List trails, inspect their configuration, and manage logging.

List trails in the account

aws cloudtrail list-trails

Show settings for one or more trails

Omit --trail-name-list to describe all trails. Omit --region to use your configured Region.

aws cloudtrail describe-trails \
  --trail-name-list "TRAIL_NAME" \
  --region us-east-1

Create a new trail

Use an existing S3 bucket with a CloudTrail delivery policy. Optional settings include --include-global-service-events, --is-multi-region-trail, --enable-log-file-validation, --cloud-watch-logs-log-group-arn, --cloud-watch-logs-role-arn, and --kms-key-id. Creating a trail does not start logging.

aws cloudtrail create-trail \
  --name "TRAIL_NAME" \
  --s3-bucket-name "BUCKET_NAME"

Start logging for a trail

aws cloudtrail start-logging --name "TRAIL_NAME"

List names and settings of all trails

aws cloudtrail describe-trails --output json

Get the status of a trail

aws cloudtrail get-trail-status --name "TRAIL_NAME"

Add tags to a trail

aws cloudtrail add-tags \
  --resource-id "TRAIL_ARN" \
  --tags-list Key=log-events,Value=management

Event History

Look up recent management events in the current Region. Event history covers the last 90 days; lookup-events can also retrieve Insights events with --event-category insight.

See the latest event in JSON format

aws cloudtrail lookup-events --max-items 1 --output json

Specify a time range

Replace these example timestamps with a range within the last 90 days. The Z suffix makes the UTC time zone explicit.

aws cloudtrail lookup-events \
  --start-time "2026-09-05T17:00:00Z" \
  --end-time "2026-09-05T18:00:00Z" \
  --output json

Query by a single attribute

Only one lookup attribute is supported per request. This example filters by event name.

aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=EventName,AttributeValue=ConsoleLogin

Investigate a potentially compromised access key

Retrieve the last 10 events associated with the key. Replace EXAMPLE_KEY_ID_HERE with the access key ID, not the secret access key.

aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=AccessKeyId,AttributeValue=EXAMPLE_KEY_ID_HERE \
  --max-items 10

Working with Trails

Trail logs are delivered as compressed JSON. Download and decompress the files before searching locally with find and jq. JSON field names are case-sensitive.

Log file location (standard account trail):

bucket_name/prefix_name/AWSLogs/ACCOUNT_ID/CloudTrail/REGION/YYYY/MM/DD/file_name.json.gz

Find user identity ARNs

Run from a directory containing decompressed CloudTrail JSON files. Uppercase UserIdentity will not match userIdentity.

find . -type f -name '*.json' \
  -exec jq '.Records[].userIdentity.arn' {} \;

Extract and sort an event timeline

Show event time, source IP address, identity ARN, and event name.

find . -type f -name '*.json' \
  -exec jq -r '.Records[] | [.eventTime, .sourceIPAddress, .userIdentity.arn, .eventName] | join(" -- ")' {} \; \
  | sort

CloudWatch Logs Analytics

CloudWatch Logs Analytics is now AWS’s recommended path for querying CloudTrail data as an alternative to CloudTrail Lake. Lake closed to new customers on May 31, 2026; existing customers can continue using it, with critical bug fixes and security updates only. Send your CloudTrail logs to CloudWatch Logs to query them with Logs Insights.

CloudTrail Lake availability and CloudWatch migration guidance ↗

Insights Events

Configure unusual API activity detection with ApiCallRateInsight and ApiErrorRateInsight. Trails support Insights on eligible management and data events; event data stores support management events only. Omitting EventCategories, as in this example, defaults to management events. Insights incurs additional charges.

Enable Insights for an existing trail

For a Lake source event data store, replace --trail-name with --event-data-store and --insights-destination, using the source and destination event data store ARNs.

aws cloudtrail put-insight-selectors \
  --trail-name "TRAIL_NAME" \
  --insight-selectors '[{"InsightType":"ApiCallRateInsight"},{"InsightType":"ApiErrorRateInsight"}]'

Retrieve Insights settings

For an event data store, replace --trail-name with --event-data-store and its ARN.

aws cloudtrail get-insight-selectors --trail-name "TRAIL_NAME"

Record Contents

Fields that make up CloudTrail log events. Not every field appears in every record; this is a reference, not an exhaustive schema.

eventTime
eventVersion
userIdentity
eventSource
eventName
awsRegion
sourceIPAddress
userAgent
errorCode
errorMessage
requestParameters
responseElements
additionalEventData
requestID
eventID
eventType
apiVersion
managementEvent
readOnly
resources
recipientAccountId
serviceEventDetails
sharedEventID
vpcEndpointId
eventCategory
addendum
sessionCredentialFromConsole
edgeDeviceDetails
tlsDetails
insightDetails

Use this cheat sheet with AI

Copy a ready-to-use prompt into your preferred AI assistant.

Goal

Preview prompt

Prompt

Use this Cybr cheat sheet as reference: CloudTrail CLI
Source: https://cybr.com/cheat-sheets/cloudtrail-cli/

My goal: Help me use these commands

Help me choose and adapt CloudTrail CLI commands for my task. Ask what I want to investigate or configure, my region and profile, and the relevant time range. Explain the chosen commands and expected output, identify placeholders, and show how to interpret the results. Distinguish lookup-events limitations from querying delivered trail logs.

Use the included reference material even if you cannot open the source URL. Ask for missing context rather than inventing my environment. Explain assumptions. For version-sensitive service behavior or commands, consult current official documentation when available, cite it, and explain any differences from this reference. If you cannot verify something, say so.

Reference material from the cheat sheet (structured text or a curated summary):

## General / Operational

List trails, inspect their configuration, and manage logging.

List trails in the account

```bash
aws cloudtrail list-trails
```

Show settings for one or more trails
Omit --trail-name-list to describe all trails. Omit --region to use your configured Region.
```bash
aws cloudtrail describe-trails \
  --trail-name-list "TRAIL_NAME" \
  --region us-east-1
```

Create a new trail
Use an existing S3 bucket with a CloudTrail delivery policy. Optional settings include --include-global-service-events, --is-multi-region-trail, --enable-log-file-validation, --cloud-watch-logs-log-group-arn, --cloud-watch-logs-role-arn, and --kms-key-id. Creating a trail does not start logging.
```bash
aws cloudtrail create-trail \
  --name "TRAIL_NAME" \
  --s3-bucket-name "BUCKET_NAME"
```

Start logging for a trail

```bash
aws cloudtrail start-logging --name "TRAIL_NAME"
```

List names and settings of all trails

```bash
aws cloudtrail describe-trails --output json
```

Get the status of a trail

```bash
aws cloudtrail get-trail-status --name "TRAIL_NAME"
```

Add tags to a trail

```bash
aws cloudtrail add-tags \
  --resource-id "TRAIL_ARN" \
  --tags-list Key=log-events,Value=management
```

## Event History

Look up recent management events in the current Region. Event history covers the last 90 days; lookup-events can also retrieve Insights events with --event-category insight.

See the latest event in JSON format

```bash
aws cloudtrail lookup-events --max-items 1 --output json
```

Specify a time range
Replace these example timestamps with a range within the last 90 days. The Z suffix makes the UTC time zone explicit.
```bash
aws cloudtrail lookup-events \
  --start-time "2026-09-05T17:00:00Z" \
  --end-time "2026-09-05T18:00:00Z" \
  --output json
```

Query by a single attribute
Only one lookup attribute is supported per request. This example filters by event name.
```bash
aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=EventName,AttributeValue=ConsoleLogin
```

Investigate a potentially compromised access key
Retrieve the last 10 events associated with the key. Replace EXAMPLE_KEY_ID_HERE with the access key ID, not the secret access key.
```bash
aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=AccessKeyId,AttributeValue=EXAMPLE_KEY_ID_HERE \
  --max-items 10
```

## Working with Trails

Trail logs are delivered as compressed JSON. Download and decompress the files before searching locally with find and jq. JSON field names are case-sensitive.

Find user identity ARNs
Run from a directory containing decompressed CloudTrail JSON files. Uppercase UserIdentity will not match userIdentity.
```bash
find . -type f -name '*.json' \
  -exec jq '.Records[].userIdentity.arn' {} \;
```

Extract and sort an event timeline
Show event time, source IP address, identity ARN, and event name.
```bash
find . -type f -name '*.json' \
  -exec jq -r '.Records[] | [.eventTime, .sourceIPAddress, .userIdentity.arn, .eventName] | join(" -- ")' {} \; \
  | sort
```

## CloudWatch Logs Analytics

CloudWatch Logs Analytics is now AWS’s recommended path for querying CloudTrail data as an alternative to CloudTrail Lake. Lake closed to new customers on May 31, 2026; existing customers can continue using it, with critical bug fixes and security updates only. Send your CloudTrail logs to CloudWatch Logs to query them with Logs Insights.

## Insights Events

Configure unusual API activity detection with ApiCallRateInsight and ApiErrorRateInsight. Trails support Insights on eligible management and data events; event data stores support management events only. Omitting EventCategories, as in this example, defaults to management events. Insights incurs additional charges.

Enable Insights for an existing trail
For a Lake source event data store, replace --trail-name with --event-data-store and --insights-destination, using the source and destination event data store ARNs.
```bash
aws cloudtrail put-insight-selectors \
  --trail-name "TRAIL_NAME" \
  --insight-selectors '[{"InsightType":"ApiCallRateInsight"},{"InsightType":"ApiErrorRateInsight"}]'
```

Retrieve Insights settings
For an event data store, replace --trail-name with --event-data-store and its ARN.
```bash
aws cloudtrail get-insight-selectors --trail-name "TRAIL_NAME"
```

More cheat sheets