For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Use doctl, the official DigitalOcean command-line interface, to create and manage DigitalOcean Secrets Manager secrets from your terminal.

Before You Begin

Make sure you have:

• doctl version 1.164.0 or later.
• An authenticated DigitalOcean account.
• Access to the team where you want to manage secrets.
• Permission to create and manage secrets.
• A supported DigitalOcean region selected for the secret.

Check Your doctl Setup

Confirm your installed version:

doctl version

Confirm that doctl is authenticated:

doctl account get

Create a Secret

Use the following command to create a secret:

doctl secrets create <secret-name> \
  --region <region> \
  --value <key>=<value>

The following example creates a secret named app-database in the nyc3 region:

doctl secrets create app-database \
  --region nyc3 \
  --value password=<value>

After the secret is created, doctl returns information about the secret, including its name, region, and current version.

Create a Secret with Multiple Values

Provide multiple --value flags to store more than one key-value pair in a secret:

doctl secrets create app-database \
  --region nyc3 \
  --value username=<username> \
  --value password=<password>

Create a Secret Interactively

Interactive mode prompts you for each key and a masked value instead of taking values on the command line, which keeps secret values out of your shell history:

doctl secrets create app-database --interactive

Create a Secret from an Environment File

Use --from-env-file to create a secret from values stored in an environment file:

doctl secrets create app-database \
  --region nyc3 \
  --from-env-file .env

Protect the environment file and do not commit it to source control.

Manage Existing Secrets

Use the following commands to manage existing secrets. Commands that act on a single secret take the secret name and its --region:

• doctl secrets list: List secrets across all regions. Values are not included.
• doctl secrets get: Retrieve a secret. Values are masked unless you add --show. To print a single value for scripting, use --key <key> --raw.
• doctl secrets set: Add or change keys without removing other keys. This creates a new version.
• doctl secrets unset: Remove the keys you name with --key. This creates a new version.
• doctl secrets update: Replace all key-value pairs. Keys you do not include are removed, and the command requires --replace.
• doctl secrets list-versions: List the retained versions of a secret.
• doctl secrets delete: Soft-delete a secret.
• doctl secrets restore: Restore a soft-deleted secret.

For the complete syntax, see the doctl secrets reference.

List Secret Versions

Use the following command to view a secret’s version history:

doctl secrets list-versions <secret-name> --region <region>

The following example lists versions of app-database in the nyc3 region:

doctl secrets list-versions app-database --region nyc3

The output includes version numbers and creation and update timestamps. This command does not change the active version. doctl does not have a revert command. To revert to a retained version, use the Revert to a Previous Version procedure in the Control Panel guide or the Revert Secret API endpoint.

Delete a Secret

Use the following command to schedule a secret for deletion. Before deleting a secret, make sure your applications no longer depend on retrieving it.

doctl secrets delete <secret-name> --region <region>

The following example schedules app-database in the nyc3 region for deletion:

doctl secrets delete app-database --region nyc3

Confirm the deletion when prompted. To skip the confirmation prompt, add --force:

doctl secrets delete app-database --region nyc3 --force

The --force flag does not permanently purge the secret. You can restore a secret scheduled for deletion.

Restore a Secret Scheduled for Deletion

Use the following command to restore a secret scheduled for deletion and make its values available again:

doctl secrets restore <secret-name> --region <region>

The following example restores app-database in the nyc3 region:

doctl secrets restore app-database --region nyc3

After restoring the secret, retrieve it to verify that its contents are available:

doctl secrets get app-database --region nyc3

Confirm that the expected keys are present. In an interactive terminal, values are masked by default. To reveal them, add --show:

doctl secrets get app-database --region nyc3 --show

Retrieving the secret verifies the restoration; it is not required to complete it. Verify that your applications can retrieve and use the secret again. Restoring a secret cancels its scheduled deletion. It does not revert the secret to an older version.

Verify a Secret

List your secrets to confirm the secret’s region and current version:

doctl secrets list

Retrieve the secret to confirm that it contains the expected keys:

doctl secrets get app-database --region nyc3

Secret values are masked in the output unless you add --show.

Protect Secret Values

Passing a secret value directly in a command may store it in your shell history. To reduce accidental exposure:

• Use interactive mode or --from-env-file when possible.
• Do not include production values in shared scripts.
• Do not commit secret values or environment files to source control.
• Avoid displaying secret values in logs, screenshots, or support requests.
• Remove commands containing sensitive values from your shell history when necessary.

Related Topics

• Manage Secrets in the Control Panel
• Versions and Rotations
• Secrets Manager Features
• Secrets Manager Limits