Introduction
The AWS CLI can retrieve secrets from AWS Secrets Manager in one command, but the output format often confuses people at first. The main detail to understand is that SecretString is usually returned as a JSON string inside a JSON response, so you often need one step to extract the field and another step to parse its contents.
Retrieve the Secret Value First
The base command is get-secret-value:
aws secretsmanager get-secret-value \
--secret-id my/app/config \
--output json
A typical response includes metadata plus either SecretString or SecretBinary. For secrets created in the console, SecretString often contains JSON such as a username and password pair.
If you only want the raw secret string, use a JMESPath query:
1aws secretsmanager get-secret-value \
2 --secret-id my/app/config \
3 --query SecretString \
4 --output text
That removes the surrounding response object and prints only the secret payload.
Parse JSON Stored in SecretString
If the secret value itself is JSON, pipe it to jq:
1aws secretsmanager get-secret-value \
2 --secret-id my/app/config \
3 --query SecretString \
4 --output text \
5| jq -r '.password' ``` That pattern is the cleanest way to extract individual fields. You can use it for any key in the stored JSON document: ```bash SECRET_JSON=$( aws secretsmanager get-secret-value \ --secret-id my/app/config \ --query SecretString \ --output text ) DB_USER=$(printf '%s' "$SECRET_JSON" | jq -r '.username') DB_PASS=$(printf '%s' "$SECRET_JSON" | jq -r '.password') printf 'User: %s\n' "$DB_USER" printf 'Password length: %s\n' "${#DB_PASS}" ``` Notice that the example prints the password length, not the password itself. That is a safer habit for debugging. ## Handle Version Stages and Previous Values Secrets Manager supports version stages such as `AWSCURRENT` and `AWSPREVIOUS`. If you need to inspect the prior value during a rotation event, request it explicitly: ```bash aws secretsmanager get-secret-value \ --secret-id my/app/config \ --version-stage AWSPREVIOUS \ --query SecretString \ --output text ``` That can be useful during a deployment rollback or when comparing what changed during rotation. ## Working with `SecretBinary` Some secrets are stored as binary data instead of a string. In that case, the CLI returns `SecretBinary`, and the value is base64-encoded in the response. You need to decode it yourself: ```bash aws secretsmanager get-secret-value \ --secret-id my/binary/secret \ --query SecretBinary \ --output text \ | base64 --decode ``` Use this path only when the secret is truly binary. Most application configuration should stay in `SecretString` because it is easier to inspect and parse safely. ## Safer Shell Patterns Secrets handling fails most often in the shell, not in AWS. A few habits reduce accidental exposure: - avoid echoing secrets into logs - avoid storing them in shell history as literal values - keep IAM permissions narrow - use a named profile or role instead of long-lived access keys Here is a safer pattern for using a secret in a subprocess: ```bash export API_TOKEN=$( aws secretsmanager get-secret-value \ --secret-id my/service/token \ --query SecretString \ --output text ) curl -H "Authorization: Bearer $API_TOKEN" https://api.example.com/health unset API_TOKEN ``` Even here, be careful with process inspection and debugging tools on shared systems. ## Common Pitfalls The most common mistake is forgetting that `SecretString` may contain JSON text rather than a plain password. If you try to use the whole string directly, your application may receive the entire JSON document instead of the one field it expects. Another frequent issue is missing permissions. Retrieving a secret requires `secretsmanager:GetSecretValue`, and if the secret uses a customer-managed KMS key, you also need `kms:Decrypt`. Quoting errors are also common, especially across shells. The AWS CLI examples are usually written for Unix-style quoting, so PowerShell and Windows Command Prompt may need different escaping. Finally, do not log the full CLI response. It contains sensitive material even if CloudTrail omits the secret value from its own event logs. ## Summary - Use `aws secretsmanager get-secret-value` to retrieve the secret payload. - Extract `SecretString` with `--query` and parse JSON with `jq`. - Use `--version-stage AWSPREVIOUS` when you need the prior rotated value. - Decode `SecretBinary` from base64 only when the secret is stored as binary. - Treat shell output and logs as part of your threat surface.
