Commander CLI as SDK

This page describes the usage of Keeper Commander CLI as a library for Python Developers

Installation

Follow the instructions below to develop or test Keeper Commander from source code, using a Python virtual environment to isolate dependencies. The Commander CLI can be used as a library or you can modify the CLI source code to fit your needs.

Clone the Commander Repository

Clone the GitHub repository to your local machine: https://github.com/Keeper-Security/Commander

git clone https://github.com/Keeper-Security/Commander
cd Commander

The "master" branch will mirror the production release. The "release" branch references the upcoming release. To optionally switch to the release branch:

git checkout release

Install Python

Install the most recent Python3 installation from python.org.

Create and Activate Virtual Environment

macOS / Linux

python3 -m venv venv
source venv/bin/activate

Windows

Install Dependencies and Set Up in Dev Mode

pip install -r requirements.txt
pip install -e .

Optional Email Dependencies

For full email provider support (OAuth, SendGrid, AWS SES), install optional dependencies:

pip install -e '.[email]'

Setup Complete

You can now launch the Commander CLI:

keeper shell

See the Logging in section to understand the authentication process. Explore all of the Commands available.

---

Python Code

Authentication

To sign into Keeper Commander with the SDK, there are two main methods:

Manual authentication

This method requires a username, then prints out the login prompts from Commander so the user can authenticate before the program continues.

from keepercommander.params import KeeperParams
from keepercommander import api

params = KeeperParams()
params.user = input('User email: ')
api.login(params) # Initiates login prompts
api.sync_down(params)

Automatic authentication

This method uses the config.json file generated when creating Persistent Login configurations. If the configuration file is valid, the program will sign into Commander without any prompts. If the configuration file is not valid or expired, the program will fall back to login prompts.

from keepercommander.__main__ import get_params_from_config

params = get_params_from_config("{{path_to_config_file}}")

---

Vault Usage

To run bash-formatted CLI commands directly from a python script, you can import the cli package from the keepercommander library and run its do_command function:

from keepercommander.__main__ import get_params_from_config
from keepercommander import cli

# Login
params = get_params_from_config("{{path_to_config_file}}")

# Execute command
cli.do_command(params, "{{cli_command}}")

The do_command function is useful for executing standalone CLI commands. It can also be run without using api.login() or api.sync_down(). It will however not return any content - e.g. you cannot leverage it to retrieve objects directly in Python.

Functions which yield python responses can be found in various directories of the keepercommander module, and will require api.login() and api.sync_down() to be ran initially. Incidentally, many useful functions can be found in the api.py package, some of which are demonstrated in the next example:

from keepercommander.__main__ import get_params_from_config
from keepercommander import api

# Login
params = get_params_from_config("{{path_to_config_file}}")
api.login(params)
api.sync_down(params)

# Search shared folder
shared_folder_name = 'Example Shared Folder'
folder_search = api.search_shared_folders(params, shared_folder_name)

# Get full record dictionaries if folder exists
keeper_folder = None
if folder_search:
    keeper_folder = folder_search[0]
    for record in keeper_folder.records:
        record_obj = api.get_record(params, record["record_uid"])
        print(record_obj.to_dictionary())
else:
    print('No folder found')

---

Enterprise Usage

Functions which access enterprise data will not retrieve any content unless the params.enterprise object is populated, which can be achieved with the api.query_enterprise() function. The following program retrieves the JSON output of an audit-report command directly in Python:

from keepercommander.__main__ import get_params_from_config
from keepercommander import api
from keepercommander.commands.aram import AuditReportCommand

from json import loads

# Login
params = get_params_from_config("{{path_to_config_file}}")
api.login(params)
api.sync_down(params)

api.query_enterprise(params) # Populate enterprise

# Get JSON report directly in Python
kwargs = {
    'report_type':'raw', 
    'format':'json',
    'limit':-1,
    'aggregate':['occurences']
}
command_class = AuditReportCommand()
command_run = command_class.execute(params, **kwargs)
report = loads(command_run)

---

You can leverage the full scope of the Commander CLI by using its internal classes and functions. Several standalone python scripts can be found here, with examples for searching records, creating teams and sharing folders, and more.