--- title: How to Manage Secrets with doctl description: Create, update, delete, and restore DigitalOcean Secrets Manager secrets with doctl. product: Secrets Manager url: https://docs.digitalocean.com/products/secrets-manager/how-to/doctl/ last_updated: "2026-11-03" --- > **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](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). # How to Manage Secrets with doctl DigitalOcean Secrets Manager provides a central place to store and manage sensitive values used by applications running on DigitalOcean. 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: ```shell doctl version ``` Confirm that doctl is authenticated: ```shell doctl account get ``` ## Create a Secret Use the following command to create a secret: ```shell doctl secrets create \ --region \ --value = ``` The following example creates a secret named `app-database` in the `nyc3` region: ```shell doctl secrets create app-database \ --region nyc3 \ --value password= ``` 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: ```shell doctl secrets create app-database \ --region nyc3 \ --value username= \ --value 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: ```shell 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: ```shell 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 --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](https://docs.digitalocean.com/reference/doctl/reference/secrets/index.html.md). ## List Secret Versions Use the following command to view a secret’s version history: ```shell doctl secrets list-versions --region ``` The following example lists versions of `app-database` in the `nyc3` region: ```shell 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](https://docs.digitalocean.com/products/secrets-manager/how-to/console/index.html.md#revert-to-a-previous-version) procedure in the Control Panel guide or the [Revert Secret](https://docs.digitalocean.com/reference/api/reference/security/index.html.md#security_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. ```shell doctl secrets delete --region ``` The following example schedules `app-database` in the `nyc3` region for deletion: ```shell doctl secrets delete app-database --region nyc3 ``` Confirm the deletion when prompted. To skip the confirmation prompt, add `--force`: ```shell 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: ```shell doctl secrets restore --region ``` The following example restores `app-database` in the `nyc3` region: ```shell doctl secrets restore app-database --region nyc3 ``` After restoring the secret, retrieve it to verify that its contents are available: ```shell 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`: ```shell 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: ```shell doctl secrets list ``` Retrieve the secret to confirm that it contains the expected keys: ```shell 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](https://docs.digitalocean.com/products/secrets-manager/how-to/console/index.html.md) - [Versions and Rotations](https://docs.digitalocean.com/products/secrets-manager/concepts/versions-and-rotations/index.html.md) - [Secrets Manager Features](https://docs.digitalocean.com/products/secrets-manager/details/features/index.html.md) - [Secrets Manager Limits](https://docs.digitalocean.com/products/secrets-manager/details/limits/index.html.md)