Directory Connector CLI

Category: Directory Connector
On this page:

    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, etc.). The Directory Connector CLI can be used cross-platform on Windows, macOS, and Linux distributions.

    Getting Started

    Complete the following steps to get started with the Bitwarden Directory Connector CLI:

    1. Download the CLI from one of the following links:
    2. Extract the .zip and move the contents (bwdc and keytar.node) to /usr/local/bin or another directory in your $PATH. Please note, keytar.node must be in the same directory as the primary bwdc executable.

      Linux Only: If not already installed, install libsecret with your package manager of choice:

      apt-get install libsecret-1-0
      brew install libsecret
      

      Windows Only: Windows users can add bwdc.exe to the current user’s PATH.

    3. Verify that the bwdc command works in your terminal by running the following:

      bwdc --help
      
    4. Connect Directory Connector to your Directory using the bwdc config <setting> <value> command (see command reference).
    5. Configure Sync Options by editing your data.json file (to learn more, see Directory Connector File Storage). Use the bwdc data-file command to obtain the absolute path of your data.json file.

      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:

    6. Run the bwdc test command to check whether your configuration would sync the expected results.
    7. Once your Directory and Sync Options are properly configured, and bwdc test yields the expected results, run the bwdc sync command to start a live sync operation.

    Commands Reference

    login

    Use the login command to login to Directory Connector with your Bitwarden Account. You must be an Admin or Owner for your Organization to use Directory Connector (for more information, see User Types and Access Controls).

    bwdc login [options] [email] [password]
    

    Options include:

    For example:

    bwdc login [email protected] mystrongpassword --method 0 --code 204678
    

    logout

    Use the logout command to logout of the Directory Connector CLI.

    bwdc logout
    

    help

    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:

    bwdc --help
    

    Use the --help option on any specific command to learn more about that command:

    bwdc test --help
    bwdc config --help
    

    test

    The 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.

    bwdc test
    

    Use the --last option to test only the changes since the last successful sync.

    bwdc test --last
    

    sync

    The sync command runs a live sync operation and pushes data to your Bitwarden Organization.

    bwdc sync
    

    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

    The last-sync command returns an ISO 8601 timestamp for the last sync operation that was performed for users or groups. You must specify either users or 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

    The config command allow you to specify your Directory settings:

    bwdc config <setting> <value>
    

    Options include:

    • server <server-url>
    • directory <directory-type>
    • ldap.password <password>
    • azure.key <key>
    • gsuite.key <key>
    • okta.token <token>
    • onelogin.secret <secret>

    ldap.password, azure.key, gsuite.key, okta.token, and onelogin.secret can only be modified from the CLI using bwdc config, or from the Desktop Application.

    data-file

    The data-file command returns an absolute path to the data.json configuration file used by the Directory Connector CLI:

    bwdc data-file
    

    Configuration settings can be modified for the Directory Connector CLI by editing the data.json configuration file directly in your favorite text editor.

    clear-cache

    The clear-cache command allows you to clear cached data that the application stores while performing sync operations. For more information, see Clear Sync Cache.

    bwdc clear-cache
    

    update

    The update command allows you to check if your Directory Connector CLI is up-to-date:

    bwdc update
    

    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.

    Warning

    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.

    Troubleshooting

    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.

    Was this helpful?

    Rate this article:

    Email Us

    Want to talk to a human?

    Send Us An Email