cloudtrail-cli

User-friendly CloudTrail CLI: simple syntax, clean tables, no AWS documentation required

Stop fighting with complex aws cloudtrail lookup-events JSON parameters. This tool changes CloudTrail queries into simple, easy commands with clean table output. Perfect for developers who want CloudTrail data without learning complex AWS CLI. No need to read AWS documentation or build complex JSON queries. Just use simple flags like --start-time and --event-source to get your data. Results show in clean, easy tables that you can understand quickly - no JSON handling needed.

🔢 Prerequisites

• An IAM Role/User with cloudtrail:LookupEvents permission.

🚀 Quick start

cloudtrail-cli --help

cloudtrail-cli --start-time 2025-05-12T00:00:00Z --end-time 2025-05-12T01:00:00Z --event-source sts.amazonaws.com --max-results 3
+--------------------------------------+-------------------+----------------------+--------------------------------+-------------------+-------------------+-------------------+----------------------+-----------+----------+
| EventId                              | EventName         | EventTime            | Username                       | EventSource       | UserAgent         | SourceIPAddress   | AccessKeyId          | ErrorCode | ReadOnly |
+--------------------------------------+-------------------+----------------------+--------------------------------+-------------------+-------------------+-------------------+----------------------+-----------+----------+
| 9a7304bb-fc9c-40ce-b148-25b875d5e534 | GetCallerIdentity | 2025-05-12T00:59:57Z | aws-go-sdk-1746934587741269082 | sts.amazonaws.com | eks.amazonaws.com | eks.amazonaws.com | ASIAEXAMPLE098765432 |           | true     |
| d0db6d59-3277-4297-8f73-72eb00c35c77 | GetCallerIdentity | 2025-05-12T00:59:52Z | aws-go-sdk-1746830061119273752 | sts.amazonaws.com | eks.amazonaws.com | eks.amazonaws.com | ASIAEXAMPLE098765432 |           | true     |
| ae8b7cb1-9b58-4897-be37-8f35ff077a99 | GetCallerIdentity | 2025-05-12T00:59:28Z | aws-go-sdk-1746830061119273752 | sts.amazonaws.com | eks.amazonaws.com | eks.amazonaws.com | ASIAEXAMPLE098765432 |           | true     |
+--------------------------------------+-------------------+----------------------+--------------------------------+-------------------+-------------------+-------------------+----------------------+-----------+----------+

FAQ

How do I get started with cloudtrail-cli?

Run cloudtrail-cli --help to see all available options and filters.

What AWS permissions do I need?

Your IAM user/role needs cloudtrail:LookupEvents permission. If you get "permission denied" errors, verify this permission is granted.

How do I filter events by time range?

Use --start-time and --end-time with RFC3339 format: 2025-05-12T00:00:00Z

What happens if I only specify --start-time or --end-time?

• If you only provide --end-time, events from 24 hours before that end time will be returned.
• If you only provide --start-time, events from that time to now will be returned.

Can I use multiple filters at once?

No, use exactly one event filter at a time due to AWS API limitations.

Why am I not getting any results?

Check if your time range contains events and ensure only one event filter is used at a time.

👷 Install

For macOS/Linux users (Recommended)

Brand new install

brew tap guessi/tap && brew update && brew install cloudtrail-cli

To upgrade version

brew update && brew upgrade cloudtrail-cli

Manually setup (Linux, Windows, macOS)

Click to expand!

For Linux users

curl -fsSL https://github.com/guessi/cloudtrail-cli/releases/latest/download/cloudtrail-cli-Linux-$(uname -m).tar.gz -o - | tar zxvf -
mv ./cloudtrail-cli /usr/local/bin/cloudtrail-cli

For macOS users

curl -fsSL https://github.com/guessi/cloudtrail-cli/releases/latest/download/cloudtrail-cli-Darwin-$(uname -m).tar.gz -o - | tar zxvf -
mv ./cloudtrail-cli /usr/local/bin/cloudtrail-cli

For Windows users

$SRC = 'https://github.com/guessi/cloudtrail-cli/releases/latest/download/cloudtrail-cli-Windows-x86_64.tar.gz'
$DST = 'C:\Temp\cloudtrail-cli-Windows-x86_64.tar.gz'
Invoke-RestMethod -Uri $SRC -OutFile $DST

⚖️ License

Apache-2.0