credring

credring is a small command-line application for storing, retrieving, and deleting credentials through the operating system keyring. It uses common.queueb.org/keyring to select native macOS, Windows, Linux, and WSL2 backends while keeping one CLI contract for people and scripts.

Credential names are command arguments and are not secret. Credential values are accepted only through standard input and are never accepted as arguments, flags, environment variables, or configuration fields.

Installation

Install the latest published source version with Go 1.27 or newer:

go install queueb.org/credring@latest

To install this release explicitly:

go install queueb.org/credring@v0.1.0

The GitHub release also provides prebuilt archives for Linux, macOS, and Windows on amd64 and arm64, together with SHA256SUMS. The first-release binaries are not code-signed and the macOS artifacts are not notarized. A checksum detects a changed download but does not authenticate its publisher. Use the normal Gatekeeper or SmartScreen approval flow, or use go install; do not disable operating-system protections globally.

Archive names use credring_0.1.0_<os>_<arch>, with .tar.gz for Linux and macOS (darwin) and .zip for Windows. Each archive contains only the platform binary and LICENSE.

Usage

Store a value interactively. Terminal input is hidden and Enter is not stored:

$ credring set my-key
Secret:

Store the exact bytes from redirected input:

$ credring set my-key < secret.bin

set replaces an existing value. Its aliases are new, n, add, a, and store.

Write a value byte-for-byte to stdout:

$ credring get my-key > secret.bin

get adds no newline or other formatting. Add a terminal delimiter explicitly when appropriate:

$ credring get my-key && echo

Delete a value:

$ credring delete my-key

The deletion aliases are del, remove, rem, and rm.

Examples intentionally avoid secret literals in shell commands because shell history and process inspection can retain them.

Backend selection

Without --backend, credring delegates discovery to the keyring library and opens one backend for the invocation. It does not fail over after an operation starts, and it never selects filesystem storage implicitly.

Inspect the effective selection and rejected candidates as YAML:

$ credring info
backend: windows-credential-manager
fallback: false
host: windows
interaction: none
persistence: persistent
rejected: []

An explicit backend may be selected with one of these names:

• secret-service;
• kernel-keyring;
• keychain;
• windows-credential-manager;
• filesystem.

On WSL2, Windows Credential Manager requires the separately released keyring-winbridge.exe to be available through the inherited Windows PATH. Without it, discovery may continue to another Linux backend; an explicitly selected Windows backend fails instead.

Filesystem storage requires an absolute root and is supported only through an explicit selection:

$ credring --backend filesystem --fs-root /secure/credring set my-key < secret.bin

Filesystem values are plaintext and depend on the confidentiality of the underlying volume. The backend rejects unsafe ownership, permissions, symlinks, and WSL DrvFS. The Linux kernel keyring is session-scoped and values may disappear after logout, environment shutdown, or reboot. Credential commands emit a warning when either of these boundaries applies.

The flags --backend, --fs-root, and --verbose have the non-secret environment defaults CR_BACKEND, CR_FS_ROOT, and CR_VERBOSE. Explicit flags take precedence. There is no environment variable for a credential value.

Exit statuses

Status	Meaning
0	successful execution
1	application, I/O, backend, or unavailable-backend failure
2	invalid command, argument, key, or configuration
3	credential not found by get or delete
130	interrupted with Ctrl-C

Scripts should use these statuses instead of parsing diagnostic text.

Security and environment status

At-rest protection, interaction, persistence, and host ownership belong to the selected backend. credring reduces the lifetime of mutable buffers where it can, but it cannot guarantee complete Go-memory zeroization or control memory owned by the backend, operating system, redirected files, pipes, or terminal.

Read the security boundary before choosing a backend. The environment support record distinguishes cross-built targets from environments exercised on a real host. Report suspected vulnerabilities privately according to SECURITY.md, and never include real credential values in a report.

Compatibility and license

Patch releases in v0.1.x preserve the documented CLI contract. Compatibility between minor releases before v1.0.0 is not guaranteed.

credring is distributed under the MIT License.