AWSCurl

0.39 · active · verified Sun Apr 12

AWSCurl is a command-line tool and Python module that provides a curl-like interface for making authenticated requests to AWS APIs. It simplifies interaction with AWS services by automatically handling AWS Signature Version 4 request signing, credential lookup, and header construction. The library supports all AWS services that utilize SigV4, including S3, CloudFront, and Lambda. Currently at version 0.39, it maintains an active release cadence with multiple updates throughout the year to introduce features and address bugs.

Warnings

gotcha Credential precedence can be confusing: Command-line arguments override environment variables, which in turn override values from `~/.aws/credentials` or `~/.aws/config` profiles.
Fix: Always explicitly define credentials using the method with the highest precedence you intend to use. For debugging, use `--verbose` to see which credentials are being loaded.
gotcha Complex query strings, particularly for Prometheus APIs with PromQL filters (e.g., `query={key="value"}`), may require manual URL encoding of the query string before passing it to `awscurl` to avoid `InvalidQueryStringException` errors.
Fix: Manually URL-encode problematic parts of your query string, or the entire query string, before passing it via the `-d` flag or in the URI.
breaking Early versions (around v0.19) had issues with Python 3's byte/string handling, leading to unparsable JSON output (prefixed with `b'`).
Fix: Upgrade `awscurl` to a newer version (0.20+) where Python 3 compatibility for output encoding has been addressed.
gotcha Using `brew install awscurl` on macOS can sometimes lead to conflicts with existing Python installations or break the AWS CLI due to dependency version mismatches.
Fix: Prefer `pip install awscurl` within a virtual environment. If using Homebrew, be aware of the Python versions it installs and how they interact with your system PATH. Consider running `awscurl` via Docker to isolate dependencies if conflicts arise.
gotcha Before v0.34, if using AWS SSO or complex AWS CLI profiles, `botocore` might not have been automatically installed or loaded, leading to `botocore package could not be loaded` errors.
Fix: Upgrade to `awscurl` v0.34 or later, which includes `botocore` as a default dependency. Alternatively, for older versions, ensure `pip install 'awscurl[awslibs]'` to include necessary AWS-related dependencies.

Install

pip install awscurl Install with pip

Quickstart

Make an authenticated GET request to list the contents of an S3 bucket. Ensure your AWS credentials are configured via environment variables, an AWS CLI profile, or provided directly via CLI flags.

# Set AWS credentials as environment variables (or configure ~/.aws/credentials)
# export AWS_ACCESS_KEY_ID="your_access_key"
# export AWS_SECRET_ACCESS_KEY="your_secret_key"
# export AWS_DEFAULT_REGION="us-east-1"

# Example: List S3 bucket content
awscurl --service s3 'https://your-bucket-name.s3.amazonaws.com/'

view raw JSON →