secret-ctl

secret-ctl is a command-line interface for interacting with the freedesktop.org Secret Service API (e.g., GNOME Keyring, KWallet) via D-Bus. It provides a JSON-based interface to list, fetch, and remove secrets with intelligent content-type handling and decoding.

Features

• JSON Output: All operations output structured JSON, making it easy to integrate with tools like jq.
• Intelligent Decoding: Automatically handles base64 encoding and various charsets based on content-type metadata.
• Unlocking: Automatically attempts to unlock locked items when fetching secrets.
• Standard Operations: Supports listing, fetching (multiple paths), and removing secrets.

Installation

cargo install --git https://github.com/andrew-grechkin/secret-ctl

Alternatively, from source:

git clone https://github.com/andrew-grechkin/secret-ctl
cd secret-ctl
cargo install --path .

XDG Compliance

By default, cargo installs binaries to ~/.cargo/bin. To make the installation XDG compliant, ensure the following environment variables are set in your shell profile (e.g., .bashrc or .zshrc):

# Move Cargo home to Data Home
export CARGO_HOME="$XDG_DATA_HOME/cargo"

# Ensure binaries go to .local/bin (XDG standard)
export CARGO_INSTALL_ROOT="$HOME/.local"

# Ensure the path is in your PATH
export PATH="$HOME/.local/bin:$PATH"

Usage

Listing Secrets

Enumerate all secrets with their metadata (path, label, attributes, etc.):

secret-ctl list

Fetching Secrets

Retrieve one or more secrets by their D-Bus object paths:

secret-ctl fetch /org/freedesktop/secrets/collection/login/1

The output will include the secret value, decoded based on its content-type. Binary data is returned as base64.

Removing Secrets

Delete one or more secrets by their D-Bus object paths:

secret-ctl remove /org/freedesktop/secrets/collection/login/1

Output Format

All commands output JSON to stdout.

Error Handling

Errors are output as JSON to stderr with the following structure:

{
  "status": "error",
  "identifier": "/path/to/secret",
  "message": "Error description"
}

License

This project is licensed under the GNU General Public License Version 2 (GPLv2). See the LICENSE file for details.