AWS Encryption SDK CLI

4.3.0 verified Fri May 01 auth: no python

Command line tool for encrypting and decrypting files and directories using the AWS Encryption SDK. Current version: 4.3.0. Release cadence: irregular, major versions follow AWS Encryption SDK updates.

pip install aws-encryption-sdk-cli

Common errors

error aws-encryption-sdk-cli: error: argument --master-keys: expected one argument ↓

cause Missing colon or incorrect format in --master-keys key=value pair. For example, 'key=arn:...' without quotes or using space instead of '='.

fix

Use correct format: --master-keys key=arn:aws:kms:... (no space around '=')

error ERROR: Unable to write to output file... ↓

cause Output directory does not exist or the process lacks write permissions.

fix

Create the output directory and verify write permissions: mkdir -p /output/dir

error aws-encryption-sdk-cli: error: unrecognized arguments: --decode ↓

cause Using old CLI flags from v1.x or v2.x. The --decode flag was removed in v4.0.0.

fix

Use decrypt subcommand without --decode. E.g., 'aws-encryption-sdk-cli decrypt --input ...'

error botocore.exceptions.NoCredentialsError: Unable to locate credentials ↓

cause AWS credentials not configured. CLI requires valid AWS credentials for KMS operations.

fix

Configure AWS credentials via environment variables, ~/.aws/credentials, or IAM role.

Warnings

breaking Version 4.0.0+ changed the CLI interface: removed --encode and --decode flags; encryption format changed to AWS Encryption SDK 2.0+ (message format v2). Existing encrypted data from v1.x SDK will not be decryptable unless migration steps are taken. ↓

fix Use aws-encryption-sdk-cli v3.x for backward compatibility, or re-encrypt data using new CLI.

deprecated The --master-keys flag is deprecated in favor of --wrapping-keys in v4.x. Old flag still works but may be removed. ↓

fix Replace --master-keys with --wrapping-keys in commands.

gotcha The CLI tool requires write permissions to the output directory. If output file exists, it will be overwritten without warning. ↓

fix Ensure output directory exists and use a unique filename to avoid accidental overwrites.

gotcha When using --input and --output for directories, the CLI encrypts/decrypts each file individually and preserves directory structure. However, files larger than available memory may fail because the SDK buffers entire files. ↓

fix For large files, use streaming options or split files before encryption.

Imports

encrypt_file
wrong
```
from aws_encryption_sdk_cli import encrypt
```
correct
```
from aws_encryption_sdk_cli import encrypt_file
```
The CLI does not expose a Python API for direct import; use subprocess or the provided entry points.

Quickstart

Basic encrypt/decrypt commands using AWS KMS. Requires AWS credentials configured.

# Encrypt a file with a KMS key
# Replace KEY_ARN and INPUT_FILE with your values
aws-encryption-sdk-cli encrypt --input /path/to/plaintext --output /path/to/ciphertext --master-keys key=arn:aws:kms:us-east-1:123456789012:key/abc123

# Decrypt the file
aws-encryption-sdk-cli decrypt --input /path/to/ciphertext --output /path/to/plaintext