aws-secretsmanager

Manage secrets stored in AWS Secrets Manager

TLDR

Show secrets stored by the secrets manager in the current account

$ aws secretsmanager list-secrets

List all secrets but only show the secret names and ARNs (easy to view)

$ aws secretsmanager list-secrets --query 'SecretList[*].{Name: Name, ARN: ARN}'

Create a secret

$ aws secretsmanager create-secret --name [name] --description "[secret_description]" --secret-string '[secret]'

Delete a secret (append --force-delete-without-recovery to delete immediately without any recovery period)

$ aws secretsmanager delete-secret --secret-id [name|arn]

View details of a secret except for secret text

$ aws secretsmanager describe-secret --secret-id [name|arn]

Retrieve the value of a secret (to get the latest version of the secret omit --version-stage)

$ aws secretsmanager get-secret-value --secret-id [name|arn] --version-stage [version_of_secret]

Rotate the secret immediately using a Lambda function

$ aws secretsmanager rotate-secret --secret-id [name|arn] --rotation-lambda-arn [arn_of_lambda_function]

Rotate the secret automatically every 30 days using a Lambda function

$ aws secretsmanager rotate-secret --secret-id [name|arn] --rotation-lambda-arn [arn_of_lambda_function] --rotation-rules AutomaticallyAfterDays=[30]

SYNOPSIS

aws secretsmanager operation [--cli-input-json | --generate-cli-skeleton] [AWS CLI global options]

--cli-input-json
    Reads arguments from JSON file or stdin

--generate-cli-skeleton
    Prints JSON skeleton for operation parameters

--output
    Output format: json|text|table (default json)

--query
    JMESPath query to filter results

--region
    AWS region (e.g., us-east-1)

--profile
    Named profile from credentials file

--endpoint-url
    Override service endpoint

--max-items
    Max number of paginated items

--no-paginate
    Disable automatic pagination

--debug
    Enable debug logging

DESCRIPTION

The aws secretsmanager command is part of the AWS Command Line Interface (CLI) for interacting with AWS Secrets Manager, a service that helps protect sensitive data like database credentials, API keys, and certificates.

It enables secure storage, retrieval, rotation, and management of secrets at scale. Key capabilities include creating secrets with automatic encryption using AWS KMS, retrieving plain-text values (with access logging), setting rotation schedules via Lambda functions, listing secrets with filters, and deleting or replicating them across regions.

Supports JSON as input/output format, pagination for large lists, and querying results with JMESPath. Ideal for automation in CI/CD pipelines, scripts, or infrastructure as code (e.g., Terraform).

Requires AWS CLI v2 (recommended) installed and configured with aws configure for credentials, region, and output format. All operations respect IAM permissions and CloudTrail auditing. Secrets Manager integrates with RDS, DocumentDB, and other services for automatic rotation.

CAVEATS

Requires AWS CLI configured with valid credentials and IAM permissions for Secrets Manager actions.
Secret values returned in plain text; handle securely.
Rotation requires Lambda permissions. Costs apply per API call and secret storage.

COMMON OPERATIONS

create-secret, delete-secret, describe-secret, get-random-password, get-secret-value, list-secrets, put-secret-value, rotate-secret, update-secret.

EXAMPLE USAGE

aws secretsmanager create-secret --name MySecret --secret-string '{"username":"admin"}'
aws secretsmanager get-secret-value --secret-id MySecret --query SecretString --output text

CONFIGURATION

Install via pip install awscli or package manager. Run aws configure for setup. Use aws secretsmanager help for full docs.

HISTORY

Introduced in AWS CLI v1.16.156 (2018) alongside Secrets Manager GA. Enhanced in CLI v2 (2020) with better performance, Markdown docs, and SSO support. Secrets Manager evolved from basic vault to multi-region replication and external secrets operator integration.