Table Of Contents


User Guide

First time using the AWS CLI? See the User Guide for help getting started.

[ aws . secretsmanager ]



Modifies the staging labels attached to a version of a secret. Staging labels are used to track a version as it progresses through the secret rotation process. You can attach a staging label to only one version of a secret at a time. If a staging label to be added is already attached to another version, then it is moved--removed from the other version first and then attached to this one. For more information about staging labels, see Staging Labels in the AWS Secrets Manager User Guide .

The staging labels that you specify in the VersionStage parameter are added to the existing list of staging labels--they don't replace it.

You can move the AWSCURRENT staging label to this version by including it in this call.


Whenever you move AWSCURRENT , Secrets Manager automatically moves the label AWSPREVIOUS to the version that AWSCURRENT was removed from.

If this action results in the last label being removed from a version, then the version is considered to be 'deprecated' and can be deleted by Secrets Manager.

Minimum permissions

To run this command, you must have the following permissions:

  • secretsmanager:UpdateSecretVersionStage
Related operations
  • To get the list of staging labels that are currently associated with a version of a secret, use `` describe-secret `` and examine the SecretVersionsToStages response value.

See also: AWS API Documentation

See 'aws help' for descriptions of global parameters.


--secret-id <value>
--version-stage <value>
[--remove-from-version-id <value>]
[--move-to-version-id <value>]
[--cli-input-json <value>]
[--generate-cli-skeleton <value>]


--secret-id (string)

Specifies the secret with the version whose list of staging labels you want to modify. You can specify either the Amazon Resource Name (ARN) or the friendly name of the secret.

--version-stage (string)

The list of staging labels to add to this version.

--remove-from-version-id (string)

(Optional) Specifies the secret version ID of the version that the staging labels are to be removed from.

If you want to move a label to a new version, you do not have to explicitly remove it with this parameter. Adding a label using the MoveToVersionId parameter automatically removes it from the old version. However, if you do include both the "MoveTo" and "RemoveFrom" parameters, then the move is successful only if the staging labels are actually present on the "RemoveFrom" version. If a staging label was on a different version than "RemoveFrom", then the request fails.

--move-to-version-id (string)

(Optional) The secret version ID that you want to add the staging labels to.

If any of the staging labels are already attached to a different version of the secret, then they are removed from that version before adding them to this version.

--cli-input-json (string) Performs service operation based on the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, the CLI values will override the JSON-provided values.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

See 'aws help' for descriptions of global parameters.


ARN -> (string)

The ARN of the secret with the staging labels that were modified.

Name -> (string)

The friendly name of the secret with the staging labels that were modified.