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)

---

Bulk Command Script

A common use-case for Commander scripts is to run a command in bulk for all records in a folder.

The script below will collect a list of folders (Shared, Personal or Nested) and run a command (by default, get) on every record within the folder (either on direct children or full recursion).

You can replace the command in the last line of the document and run the script to execute it on every record in your folder selection.

from keepercommander.params import KeeperParams
from keepercommander import api, cli
from keepercommander.subfolder import get_contained_record_uids

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

# Basic CLI to collect folders
folder_list = []
folders_complete = False
while not folders_complete:
    folder_prompt = input('Enter a shared folder name / UID (enter / if all shared folders added): ')
    if folder_prompt == '/':
        # Deduplicate
        folder_list = list(set(folder_list))
        print(folder_list)
        confirm = input('Are all these folder names valid? (y/n) ')
        if confirm.lower() == 'y':
            folders_complete = True
        elif confirm.lower() == 'n':
            print('Restarting...')
            folder_list = []
        else:
            print('Wrong input')
    else:
        folder_list.append(folder_prompt)
recursive_complete = False
# Basic CLI to enable/disable recursive execution
while not recursive_complete:
    recursive_input = input('Only execute commands for direct children records (y/n)? ')
    if recursive_input.lower() == 'n':
        children_only = False
        recursive_complete = True
    elif recursive_input.lower() == 'y':
        children_only = True
        recursive_complete = True

# Iterate through collected folder names
keeper_folders = {params.folder_cache[x].name:x for x in params.folder_cache}
selected_folder_uids = []
for folder in folder_list:
    # entry is a UID
    if folder in params.folder_cache:
        selected_folder_uids.append(folder)
    # entry is a name
    elif folder in keeper_folders:
        selected_folder_uids.append(keeper_folders[folder])
    # entry not found
    else:
        print(f'No folder found for {folder}')
    
# Enumerate folder content
record_uids = []
for uid in selected_folder_uids:
    content = get_contained_record_uids(params, uid, children_only)
    for folder in content:
        record_uids += [x for x in content[folder]]
# Deduplicate
record_uids = list(set(record_uids))

# Run bulk command
for uid in record_uids:
    cli.do_command(params,f'get {uid}') # <-- Replace with your command

---

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.