obscuro auth

Prerequisites

obscuro auth uses your OS keychain via the Secret Service API on Linux, Keychain on macOS, and Credential Manager on Windows.

Linux

A running Secret Service provider is required. Install one of:

GNOME Keyring (sudo apt-get install gnome-keyring on Debian/Ubuntu; sudo dnf install gnome-keyring on Fedora)
KeePassXC with secret-service integration enabled (Tools → Settings → Secret Service Integration → Enable)
KWallet with the secret-service module

Headless servers, minimal containers, and CI runners typically have no Secret Service provider — see "Keychain unavailable?" below.

macOS

Keychain is available by default. The login keychain must be unlocked (it usually is after login).

Windows

Credential Manager is available by default on Windows 10 and later.

When you run obscuro auth store, an interactive selector lets you pick your password backend (OS keychain or managed file). Run obscuro auth doctor to see which backends are available first.

Keychain unavailable? If your host has no keychain (headless Linux, minimal container, CI runner), pick the managed-file backend from the selector, or use one of these alternatives:

obscuro <cmd> --password-file /path/to/pw — read the master password from a file (mode 600 recommended)
obscuro <cmd> --password-file - — read from stdin (useful in pipes)
OBSCURO_PASSWORD=... obscuro <cmd> — pass via environment variable

See configuration for the full password-resolution order.

For a full walkthrough per distro, plus dbus verification and common failure modes, see Troubleshooting.

Subcommands

auth doctor

obscuro auth doctor

Prints a table of detected password backends with availability and diagnostics for each row. This is diagnostic-only — runs minimal transient probes (sentinel keychain entry + temp file, both immediately deleted) without modifying vault config or stored passwords.

Sample output:

obscuro auth doctor — backend availability
[✓] keychain: OS keychain — ready
    DBUS_SESSION_BUS_ADDRESS: unix:path=/run/user/1000/bus
    XDG_SESSION_TYPE: x11
[✗] keychain: OS keychain — Secret Service reachable but login collection is locked/missing — try 'secret-tool store' first, or use file backend
[✓] file: managed file — ready — writes to /root/.config/obscuro/vaults/a1b2c3d4e5f6a7b8.pw

Always exits 0, even if all backends are unavailable.

auth store

obscuro auth store

Prompts for your master password, then launches an interactive selector so you can pick which backend stores it (OS keychain or managed file, keyed by your vault's salt).

Flags:

--backend=keychain|file — Pass --backend=keychain or --backend=file to skip the interactive selector (useful in CI/scripts). If the chosen backend is unavailable, exits with code 3.
--verbose — Also available on auth status and auth doctor. Expands each row with full diagnostics.

Exit codes:

Exit code	Meaning
`0`	Password stored successfully.
`1`	Config/crypto error (vault not initialized, wrong password, disk I/O).
`2`	Non-TTY session and no `--backend` flag, or user cancelled the selector. Stderr lists the flag recipes to run non-interactively.
`3`	`--backend=<name>` was passed but that backend is not available on this host. Stderr shows the underlying reason from the detector.

Scriptable example:

if obscuro auth store --backend=keychain 2>/dev/null; then
  echo "stored in keychain"
elif [ $? -eq 3 ]; then
  obscuro auth store --backend=file
fi

auth clear

obscuro auth clear

Removes the stored password from the keychain.

auth status

obscuro auth status

Tells you whether a password is currently saved in the keychain.

Supported Keychains

OS	Backend
macOS	Keychain
Linux	Secret Service (DBUS)
Windows	Credential Manager

Under the hood, this uses go-keyring.

Prefer obscuro auth doctor first — it prints exactly which backends are working right now with only transient probe side effects.

obscuro auth

On this page