libsecret Setup Guide

9/8/25Less than 1 minute

This CLI enables secure authentication and persistent token caching by storing credentials in your system's keychain. It uses @azure/msal-node for authentication, which relies on the keytar module for secure credential storage.

What is libsecret?
libsecret is a library for storing and retrieving passwords and secrets. On Linux, keytar depends on libsecret to access the system keyring.

Common Issue: Cannot find module '../build/Release/keytar.node'
This error occurs when the keytar native module isn't properly built or installed. It can happen on any platform (Windows, macOS, Linux) and usually indicates missing build tools or failed native compilation.

Platform Requirements

Windows: No additional dependencies. keytar uses the Windows Credential Manager.
macOS: No additional dependencies. keytar uses the macOS Keychain. If you encounter unusual issues (rare), you can optionally try installing libsecret:
```
brew install libsecret
```
Linux: You must install libsecret for secure credential storage. See below for instructions.

Windows Installation

While Windows doesn't require libsecret, you may encounter keytar native module issues. Ensure you have the necessary build tools:

Prerequisites

Visual Studio Build Tools or Visual Studio Community with C++ workload
Python (for node-gyp)
Node.js with npm/yarn

Installation Steps

Install Visual Studio Build Tools:
- Download from Microsoft Visual Studio
- Select "C++ build tools" workload
- Or install via command line:
```
# Using winget
winget install Microsoft.VisualStudio.2022.BuildTools
```

Install Python (if not already installed):

# Using winget
winget install Python.Python.3.11

Rebuild keytar:

npm rebuild keytar
# or
yarn rebuild keytar

Linux Installation

Install the libsecret library based on your distribution:

Ubuntu/Debian:
```
sudo apt-get update
sudo apt-get install -y libsecret-1-0 libsecret-1-dev
```
Both runtime and development packages are required for building native modules.
Fedora:
```
sudo dnf install -y libsecret libsecret-devel
```
Install both runtime and development packages if you plan to build native modules.
Arch Linux:
```
sudo pacman -S --noconfirm libsecret
```

Verifying Installation

After installing libsecret, rebuild keytar to ensure it links correctly:

npm rebuild keytar

You can verify that keytar is working by running your CLI and checking for credential storage warnings. Alternatively, you can test with a simple script:

const keytar = require('keytar');
keytar.setPassword('test-service', 'test-account', 'test-password')
  .then(() => keytar.getPassword('test-service', 'test-account'))
  .then(console.log)
  .catch(console.error);

If you see errors related to keytar or libsecret, see troubleshooting below.

Ensure Visual Studio Build Tools are installed with C++ workload
Install Python for node-gyp
Rebuild keytar: npm rebuild keytar or yarn rebuild keytar

macOS:

Ensure Xcode Command Line Tools are installed: xcode-select --install
Rebuild keytar: npm rebuild keytar

Linux:

Install libsecret development packages (see Linux Installation section)
Rebuild keytar: npm rebuild keytar

Missing `libsecret` errors (Linux only)

Ensure you have installed both the runtime and development packages (e.g., libsecret-1-0 and libsecret-1-dev on Ubuntu/Debian).

General Solutions

Rebuild keytar:

npm rebuild keytar
# or
yarn rebuild keytar

Clean install:

rm -rf node_modules package-lock.json
npm install
# or
rm -rf node_modules yarn.lock
yarn install

Still having issues?

Windows: Check that Visual Studio Build Tools are properly installed and Python is in your PATH
macOS: Verify Xcode Command Line Tools are installed and up to date
Linux: Ensure your system keyring (e.g., GNOME Keyring or KWallet) is running and unlocked. On some headless or minimal Linux environments, you may need to start or configure the keyring daemon manually.
See the keytar troubleshooting guide.
Consult your distribution's documentation for keyring setup.