Secrets CLI (legacy)
Important
This documentation has been retired and might not be updated.
This information applies to legacy Databricks CLI versions 0.18 and below. Databricks recommends that you use newer Databricks CLI version 0.205 or above instead. See What is the Databricks CLI?. To find your version of the Databricks CLI, run databricks -v.
To migrate from Databricks CLI version 0.18 or below to Databricks CLI version 0.205 or above, see Databricks CLI migration.
You run Databricks secrets CLI subcommands by appending them to databricks secrets. These subcommands call the Secrets API.
For more information about secrets, see Secret management.
Note
The Secrets CLI requires Databricks CLI 0.7.1 or above.
databricks secrets --help
Usage: databricks secrets [OPTIONS] COMMAND [ARGS]...
Utility to interact with secret API.
Options:
-v, --version [VERSION]
--profile TEXT CLI connection profile to use. The default profile is
"DEFAULT".
-h, --help Show this message and exit.
Commands:
create-scope Creates a secret scope.
Options:
--scope SCOPE The name of the secret scope.
--initial-manage-principal The initial principal that can manage the created secret scope.
If specified, the initial ACL with MANAGE permission applied
to the scope is assigned to the supplied principal (user or group).
The only supported principal is the group
"users", which contains all users in the workspace. If not
specified, the initial ACL with MANAGE permission applied to
the scope is assigned to request issuer's user identity.
delete Deletes a secret.
Options:
--scope SCOPE The name of the secret scope.
--key KEY The name of secret key.
delete-acl Deletes an access control rule for a principal.
Options:
--scope SCOPE The name of the scope.
--principal PRINCIPAL The name of the principal.
delete-scope Deletes a secret scope.
Options:
--scope SCOPE The name of the secret scope.
get-acl Gets the details for an access control rule.
Options:
--scope SCOPE The name of the secret scope.
--principal PRINCIPAL The name of the principal.
--output FORMAT JSON or TABLE. Set to TABLE by default.
list Lists all the secrets in a scope.
Options:
--scope SCOPE The name of the secret scope.
--output FORMAT JSON or TABLE. Set to TABLE by default.
list-acls Lists all access control rules for a given secret scope.
Options:
--scope SCOPE The name of the secret scope.
--output FORMAT JSON or TABLE. Set to TABLE by default.
list-scopes Lists all secret scopes.
--output FORMAT JSON or TABLE. Set to TABLE by default.
put Puts a secret in a scope.
Options:
--scope SCOPE The name of the secret scope.
--key KEY The name of the secret key.
--string-value TEXT Read value from string and stored in UTF-8 (MB4) form
--binary-file PATH Read value from binary-file and stored as bytes.
put-acl Creates or overwrites an access control rule for a principal
applied to a given secret scope.
Options:
--scope SCOPE The name of the secret scope.
--principal PRINCIPAL The name of the principal.
--permission [MANAGE|WRITE|READ] The permission to apply.
write Puts a secret in a scope. "write" is an alias for "put".
Options:
--scope SCOPE The name of the secret scope.
--key KEY The name of the secret key.
--string-value TEXT Read value from string and stored in UTF-8 (MB4) form
--binary-file PATH Read value from binary-file and stored as bytes.
write-acl Creates or overwrites an access control rule for a principal
applied to a given secret scope. "write-acl" is an alias for
"put-acl".
Options:
--scope SCOPE The name of the secret scope.
--principal PRINCIPAL The name of the principal.
--permission [MANAGE|WRITE|READ] The permission to apply.
Create a secret scope
To display usage documentation, run databricks secrets create-scope --help.
databricks secrets create-scope --scope my-scope
If successful, no output is displayed.
To use the Databricks CLI to create an Azure Key Vault-backed secret scope, run databricks secrets create-scope --help to display information about additional --scope-backend-type, --resource-id, and --dns-name options. For more information, see Secret management.
Delete a secret
To display usage documentation, run databricks secrets delete --help.
databricks secrets delete --scope my-scope --key my-key
If successful, no output is displayed.
Revoke an ACL for a principal
To display usage documentation, run databricks secrets delete-acl --help.
databricks secrets delete-acl --scope my-scope --principal someone@example.com
If successful, no output is displayed.
Delete a secret scope
To display usage documentation, run databricks secrets delete-scope --help.
databricks secrets delete-scope --scope my-scope
If successful, no output is displayed.
Get an ACL for a principal
To display usage documentation, run databricks secrets get-acl --help.
databricks secrets get-acl --scope my-scope --principal someone@example.com --output JSON
{
"principal": "sonmeone@example.com",
"permission": "MANAGE"
}
List the secret keys stored within a secret scope
To display usage documentation, run databricks secrets list --help.
databricks secrets list --scope my-scope --output JSON
{
"secrets": [
{
"key": "my-key",
"last_updated_timestamp": 1621284092605
}
]
}
Note
You cannot access secret values by using the Databricks CLI. To access secret values, you must use the Databricks Utilities secrets utility within a Databricks notebook.
List the ACLs for a secret scope
To display usage documentation, run databricks secrets list-acls --help.
databricks secrets list-acls --scope my-scope --output JSON
{
"items": [
{
"principal": "someone@example.com",
"permission": "MANAGE"
}
]
}
List all available secret scopes in the workspace
To display usage documentation, run databricks secrets list-scopes --help.
databricks secrets list-scopes --output JSON
{
"scopes": [
{
"name": "my-scope",
"backend_type": "DATABRICKS"
}
]
}
Create or update a secret
To display usage documentation, run databricks secrets put --help or databricks secrets write --help.
There are three ways to store a secret. The easiest way is to use the --string-value option;
the secret will be stored in UTF-8 (MB4) form. You should be careful with this option, because
your secret may be stored in your command line history in plain text.
databricks secrets put --scope my-scope --key my-key --string-value my-value
Or:
databricks secrets write --scope my-scope --key my-key --string-value my-value
If successful, no output is displayed.
You can also use the --binary-file option to provide a secret stored in a file. The file content will be
read as is and stored as bytes.
databricks secrets put --scope my-scope --key my-key --binary-file my-secret.txt
Or:
databricks secrets write --scope my-scope --key my-key --binary-file my-secret.txt
If successful, no output is displayed.
If you don’t specify an option, an editor will be opened for you to enter your secret. Follow the instructions shown in the editor to enter your secret.
databricks secrets put --scope my-scope --key my-key
Or:
databricks secrets write --scope my-scope --key my-key
# ----------------------------------------------------------------------
# Do not edit the above line. Everything below it will be ignored.
# Please input your secret value above the line. Text will be stored in
# UTF-8 (MB4) form and any trailing new line will be stripped.
# Exit without saving will abort writing secret.
Grant or change an ACL to a secret scope for a principal
To display usage documentation, run databricks secrets put-acl --help or databricks secrets write-acl --help.
databricks secrets put-acl --scope my-scope --principal someone@example.com --permission MANAGE
Or:
databricks secrets write-acl --scope my-scope --principal someone@example.com --permission MANAGE
If successful, no output is displayed.