# Commander CLI as SDK

### 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](https://www.python.org/).

### Create and Activate Virtual Environment

{% tabs %}
{% tab title="macOS / Linux" %}

```
python3 -m venv venv
source venv/bin/activate
```

{% endtab %}

{% tab title="Windows" %}

```
python -m venv venv
.\venv\Scripts\activate
```

{% endtab %}
{% endtabs %}

### 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](https://docs.keeper.io/en/keeperpam/commander-cli/commander-installation-setup/logging-in) section to understand the authentication process. [Explore](https://docs.keeper.io/en/keeperpam/commander-cli/command-reference) 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.

```python
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](https://docs.keeper.io/en/keeperpam/commander-cli/configuration/configuration#creating-a-persistent-login-config). 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.

```python
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](https://docs.keeper.io/en/keeperpam/commander-cli/command-reference) directly from a python script, you can import the `cli` package from the `keepercommander` library and run its `do_command` function:

```python
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](https://github.com/Keeper-Security/Commander/tree/master/keepercommander), 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](https://github.com/Keeper-Security/Commander/blob/master/keepercommander/api.py), some of which are demonstrated in the next example:

```python
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:

```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](https://github.com/Keeper-Security/Commander/tree/master/examples), with examples for searching records, creating teams and sharing folders, and more.<br>