secret-tool

Store a secret with an optional label

$ secret-tool store --label=[label] [key] [value]

$ secret-tool lookup key [key]

$ secret-tool search key [key]

$ secret-tool clear key [key]

secret-tool [OPTIONS] COMMAND [ARGUMENTS]

Common COMMANDs:
   store [--label=LABEL] [--collection=COLLECTION] [--no-confirm] [--replace] ATTRIBUTE1 VALUE1 [ATTRIBUTE2 VALUE2 ...]
   lookup [--collection=COLLECTION] ATTRIBUTE1 VALUE1 [ATTRIBUTE2 VALUE2 ...]
   clear [--collection=COLLECTION] ATTRIBUTE1 VALUE1 [ATTRIBUTE2 VALUE2 ...]
   search [--collection=COLLECTION] ATTRIBUTE1 VALUE1 [ATTRIBUTE2 VALUE2 ...]
   list [--collection=COLLECTION]
   lock [COLLECTION...]
   unlock [COLLECTION...]
   version

--label=
    A descriptive name for the secret. Used when storing or as an identifier in searches.

--collection=
    Specifies the collection (keyring) to operate on. Defaults to the 'login' collection if not specified.

--no-confirm
    Prevents interactive confirmation prompts, making it suitable for non-interactive scripts.

--prompt
    Forces an interactive prompt for a password or label, even if standard input could otherwise be used.

--replace
    When used with the 'store' command, replaces an existing secret if its attributes match the new one.

--session=
    Connects to a specific D-Bus session for Secret Service communication, typically for debugging or advanced setups.

ATTRIBUTE VALUE
    Key-value pairs (e.g., 'service' 'web', 'user' 'john') used to identify, describe, and search for secrets. At least one attribute pair is usually required when storing or looking up secrets.

secret-tool is a command-line utility designed to interact with the Secret Service API, a standardized interface for securely storing and retrieving sensitive information such as passwords, API keys, and other credentials. It provides a robust, programmatic way to manage secrets typically handled by desktop keyring systems like gnome-keyring or KDE Wallet.

Users can perform various operations including storing new secrets, retrieving existing ones based on specific attributes, clearing sensitive data, or searching for secrets matching certain criteria. This tool is invaluable for scripts and automated processes that need to handle confidential data without exposing it directly in plain text. It encrypts secrets and often requires user authentication (e.g., a master password) to access the underlying keyring, ensuring data protection even in compromised environments. Its seamless integration with modern desktop environments makes it a powerful and secure solution for managing credentials across a wide range of applications.

secret-tool requires a running Secret Service API backend, such as gnome-keyring-daemon or kwalletd, to function correctly. Without a compatible backend, it will fail to connect and manage secrets.

Care must be taken when using secret-tool in shell scripts, as sensitive data printed to stdout (e.g., by lookup) might be exposed in shell history or logs if not handled securely. It's recommended to pipe output directly to other commands or variables that handle sensitive data securely.

secret-tool operates through various subcommands, each performing a specific action on your secret keyring:

   store: Used to add a new secret. It requires a label, attribute-value pairs for identification, and reads the secret value from standard input.
   lookup: Retrieves and prints the value of a secret matching the specified attributes to standard output.
   clear: Deletes secrets from the keyring that match the provided attribute-value pairs.
   search: Finds and lists the labels of secrets that match the given attributes, without revealing their values.
   list: Displays all items (labels and their attributes) within a specified collection, useful for an overview of stored secrets.
   lock: Locks one or more specified collections, making their secrets inaccessible until unlocked, often requiring user authentication.
   unlock: Unlocks one or more specified collections, allowing access to their secrets.
   version: Prints the version information for the secret-tool utility.

Secrets in secret-tool are not just identified by a label; they are primarily indexed by a set of arbitrary key-value string pairs known as attributes. For example, a secret might have attributes like 'service' 'gmail' and 'username' 'user@example.com'. These attributes enable flexible and powerful searching for secrets, allowing you to retrieve specific credentials based on multiple criteria rather than just a single name. When storing a secret, at least one attribute pair is typically required, and these pairs are crucial for future lookups and deletions.

secret-tool is part of the libsecret library, which provides the client-side implementation of the Secret Service API. This API and its tools were developed primarily for the GNOME desktop environment to offer a secure and standardized way for applications to store and retrieve sensitive data. It evolved from earlier keyring management utilities, aiming for better integration and adherence to a cross-desktop standard. Its development focuses on providing robust cryptographic protection for stored secrets and seamless integration with user authentication mechanisms.

gnome-keyring-daemon(1), kwalletd(1), seahorse(1), pass(1)