Skip to main content

Directory Connector Command Line Interface

The Directory Connector Command Line Interface (CLI) is appropriate for:

  • Work in environments where a desktop GUI is unavailable.

  • If you want to programmatically script directory sync operations using tools provided by the operating system. For example, cron jobs and scheduled task.

  • The Directory Connector CLI can be used on Linux distributions.

Setting up Directory Connector command line interface

Note

If you are setting authentication values, such as keys or secrets, in the Directory Connector data.json file, you must use the directory connector desktop application to set these values. This is because authentication values of this type cannot be set in plain text using the CLI, they must use the encrypted version that the desktop application inputs for you.

To get started using the Directory Connector CLI:

  1. Download CLI.

  2. Extract the .zip and move the contents to /usr/local/bin or another directory in your $PATH.

  3. Windows Only: Add bsafedc.exe to the current user's PATH.

  4. Verify that the bsafedc command works in your terminal by running the following:

    bsafedc --help

    Connect Directory Connector to your directory using the bsafedc config <setting> <value> command (link below). See Commands Reference.

  5. Configure sync options by editing your data.json file. See Directory Connector File Storage for more information.

    Use the bsafedc data-file command (link below) 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 bsafedc test command (link below) to check whether your configuration would sync the expected results.

  7. Once your directory and sync options are properly configured, and bsafedc test yields the expected results, run the bsafedc sync command (link below) to start a live sync operation.

See

Commands Reference

login

Use the login command to login to Directory Connector with your Team API Key. If you do not have the API Key, reach out to the Team owner. There are a few ways to use the login command:

  • By itself:

    bsafedc login

    Passing Bsafedc Login by itself will prompt you to subsequently enter client_id and client_secret.

  • With parameters:

    bsafedc login organization.b5351047-89b6-820f-ad21016b6222 yUMB4trbqV1bavh

  • With saved environment variables:

    BSAFEDC_CLINTID="organization.b5351047-89b6-820f-ad21016b6222" BSAFEDC_CLIENTSECRET="yUMB4trbqV1bavhEHGqbuGpz4AlHm9"
    bsafedc login

    Saving the environment variables BSAFEDC_CLINTID and BSAFEDC_CLIENTSECRET allows you to login to Directory Connector using only bsafedc login, which will check for those variables and use them if present.

    If these environment variables are not present, you will be prompted to enter your client_id and client_secret.

logout

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

bsafedc logout

help

The Directory Connector CLI is self-documented with --help content and examples for every command. List all available commands using the global --help option:

bsafedc --help

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

bsafedc test --help

bsafedc 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 Team whenever you run a real sync operation.

bsafedc test

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

bsafedc test --last

sync

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

bsafedc sync

Synced users and groups will be immediately available in your Team. Newly added users will receive an email invite to your Team.

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:

bsafedc 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:

bsafedc 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 bsafedc config , or from the desktop application.

  • directory-type Values

  • Active Directory/LDAP 0

  • Azure Active Directory 1

  • Google Workspace/GSuite 2

  • Okta 3

  • OneLogin 4

data-file

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

bsafedc 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. See Clear Sync Cache for more information.

bsafedc clear-cache

Troubleshooting

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:

export NODE_EXTRA_CA_CERTS="absolute/path/to/your/certificates.pem"

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.

In this section: