I needed to know why a simple command failed, but all I saw was silence. No clues. No warnings. No errors worth the name. If you’ve been there, you know the frustration. That’s when debug logging in the AWS CLI stops being optional—and becomes the fastest way to see exactly what’s going on under the hood.
AWS CLI debug logging shows you every request, every header, every byte of the response from AWS services. It turns the black box into a glass box. The easiest way to enable it is to add --debug to your command:
aws s3 ls --debug
Now instead of guessing, you see the raw HTTP requests sent to AWS, the endpoint URLs, the detailed authentication steps, the status codes, and any error payloads. If the CLI isn’t even hitting the API—maybe due to bad credentials, wrong profiles, or faulty endpoint settings—you’ll see it instantly.
You can also set the AWS_DEBUG environment variable to enable consistent logging session-wide:
export AWS_DEBUG=1
or use the cli_follow_urlparam and profile configs in ~/.aws/config to make debug mode part of your workflow when needed.
While debug mode is powerful, it is verbose. Log output will contain sensitive data like access keys or tokens if not handled with care. Always save and share logs securely. Best practice: use temporary credentials and rotate them regularly if you’re sending debug logs to any third party.
When troubleshooting permissions issues with IAM, debug logs reveal the actual request parameters and operation names AWS receives. This helps isolate whether a denied action is due to malformed parameters, implicit denies, or missing IAM statements. For S3, debug mode is indispensable to see if the CLI is targeting the correct region or if redirect loops occur due to bucket location mismatch.
For network-related issues—timeouts, connection errors, SSL problems—the debug trace will show you DNS lookups, TLS handshakes, and retries. You can pinpoint whether the delay is on AWS’s end, your network path, or misconfiguration in your VPC endpoints.
A well-tuned debug session can cut hours off a troubleshooting task. The CLI offers granularity that complements CloudTrail logs and service-specific diagnostics. By pairing debug logs with timestamps and known failing scenarios, you can reproduce issues on demand and validate fixes fast.
You don’t have to stop at reading the logs—you can build on them. Pipe debug output into analysis tools or integrate them into monitoring. That creates a feedback loop where failures are understood in minutes, not days.
If you want to go further—capturing real API traffic, linking it to your user actions, and seeing results immediately—there are platforms that make it seamless. With hoop.dev, you can spin up live, observable AWS CLI sessions in minutes, with every request and response visible in real time. Try it and see your AWS CLI debug logs come alive before your next deploy.