Directory Connector CLI
The Directory Connector CLI is suited toward work in environments where a desktop GUI is unavailable, or if you want to programmatically script directory sync operations using tools provided by the operating system (cron job, scheduled task, and more). The Directory Connector CLI can be used cross-platform on Windows, macOS, and Linux distributions.
Since the Directory Connector CLI and desktop app share the same configuration file, we recommend using the desktop app for simpler configuration experience and then using the CLI, with its shared configuration, for scheduling ongoing syncs.
To get started using the Bitwarden Directory Connector CLI:
Download the CLI from one of the following links:
.zipand move the contents (
/usr/local/binor another directory in your
$PATH. Please note,
keytar.nodemust be in the same directory as the primary
Linux only: If not already installed, install
libsecretwith your package manager of choice:
apt-get install libsecret-1-0 brew install libsecret
Windows only: Windows users can add
bwdc.exeto the current user's
Verify that the
bwdccommand works in your terminal by running the following:
Connect Directory Connector to your directory using the
bwdc config <setting> <value>command (see here).
Configure sync options by editing your
data.jsonfile (to learn more, see Directory Connector File Storage). Use the
bwdc data-filecommand to obtain the absolute path of your
Available sync options depend on the directory type in use, so refer to one of the following articles for a list of options available to you:
bwdc testcommand to check whether your configuration would sync the expected results.
Once your directory and sync options are properly configured, and
bwdc testyields the expected results, run the
bwdc synccommand to start a live sync operation.
login command to log in to Directory Connector with your organization API key. If you don't have the API key, reach out to an organization owner. There are a few ways to use the
bwdc loginby itself will prompt you to subsequently enter
bwdc login organization.b5351047-89b6-820f-ad21016b6222 yUMB4trbqV1bavhEHGqbuGpz4AlHm9
With saved environment variables:
BW_CLIENTID="organization.b5351047-89b6-820f-ad21016b6222" BW_CLIENTSECRET="yUMB4trbqV1bavhEHGqbuGpz4AlHm9" bwdc login
Saving the environment variables
BW_CLIENTSECRETallows you to login to Directory Connector using only
bwdc login, which will check for those variables and use them if present.
If these environment variables aren't present, you will be prompted to enter your
logout command to logout of the Directory Connector CLI.
The Bitwarden Directory Connector CLI is self-documented with
--help content and examples for every command. List all available commands using the global
--help option on any specific command to learn more about that command:
bwdc test --help bwdc config --help
test command queries your directory and prints a JSON formatted array of groups and users that would be synced to your Bitwarden organization whenever you run a real sync operation.
--last option to test only the changes since the last successful sync.
bwdc test --last
sync command runs a live sync operation and pushes data to your Bitwarden organization.
Synced users and groups will be immediately available in your Bitwarden organization. Newly added users will receive an email invite to your organization.
last-sync command returns an ISO 8601 timestamp for the last sync operation that was performed for users or groups. You must specify either
groups as an
<object> to run the command against:
bwdc last-sync <object>
Returns an empty response if no sync has been performed for the given object.
config command allow you to specify your directory settings:
bwdc config <setting> <value>
Available options are:
||URL of your self-hosted installation.|
||Type of directory to use. See the following table for enumerated values.|
||Password for connection to the LDAP server.|
||Azure AD secret key.|
||Google Workspace/GSuite private key.|
||OneLogin client secret.|
|Azure Active Directory||1|
data-file command returns an absolute path to the
data.json configuration file used by the Directory Connector CLI:
Some configuration settings can be modified for the Directory Connector CLI by editing the
data.json configuration file directly in your favorite text editor, however
onelogin.secret can only be modified from the CLI using
config#config, or from the desktop app.
clear-cache command allows you to clear cached data that the application stores while performing sync operations. For more information, see Clear Sync Cache.
update command allows you to check if your Directory Connector CLI is up-to-date:
If a newer version is found, the command will return a URL to download a new version. The Directory Connector CLI will not automatically update. You will need to use this URL download the new version manually.
If you using the CLI and desktop app together, it is important to ensure their versions match whenever in use. Running two different versions may cause unexpected issues.
Check the version of the Directory Connector CLI using the
--version global option.
If you receive an error message referring to the libsecret shared object
Error: libsecret-1.so.0: cannot open shared object file: No such file or directory, you may need to install libsecret which is required to store things securely on the host.
If you receive an error message referring to the dbus when using
bwdc config, for example
Failed to execute child process "dbus-launch" (No such file or directory) or
Cannot autolaunch D-Bus without X11, assign the following environment variable to allow plaintext storage of secrets in
Unable to get local issuer certificate
If you receive an error message that states
unable to get local issuer certificate, set the
NODE_EXTRA_CA_CERTS variable to your
root.pem, for example:
If you're using the desktop app, this may also manifest as the following error:
Warning: Setting the NODE_TLS_REJECT_UNAUTHORIZED environment variable to '0' makes TLS connections and HTTPS requests insecure by disabling certificate verification.