Logging in

Information and detail around authentication to the Commander CLI

First Login on a New Device

To login to Commander for the first time, click the Keeper Commander icon or open a shell and type:
$ keeper shell
Once the shell is open, begin the login by typing login. If this is your first login, you will need to follow the device approval workflow. This is only needed once, as an extra layer of security to trust the device you are on.
First Login Example:
Not logged in> login
... User(Email): [email protected]
Logging in to Keeper Commander
Device Approval Required
Approve by selecting a method below:
"email_send" to send email
"email_code=<code>" to validate verification code sent via email
"keeper_push" to send Keeper Push notification
"2fa_send" to send 2FA code
"2fa_code=<code>" to validate a code provided by 2FA application
"approval_check" check for device approval
Type your selection:
  • If you wish to approve via email:
    • Type email_sendor es
    • Enter the security code via email_code=<code>
  • If you wish to approve via Keeper Push:
    • Type keeper_push
    • Approve via push
    • Type approval_check
  • If you wish to approve via 2fa code:
    • Input 2fa_send
    • Input 2fa_code=<code>
Once complete you will receive the following message:
Device was approved

Logging in with a Master Password

After device approval, you will immediately move to the login process, or if you previously approved the device, this will be the first step.
Login Example (approved device):
Not logged in> login
... User(Email): [email protected]
Logging in to Keeper Commander
Enter password for [email protected]
Password: *********
Successfully authenticated with Login V3 (Password)
Syncing...
Decrypted [23] record(s)
My Vault>

Logging in With 2FA

If you have 2FA enforced on your account, you will be required to pass the 2FA step before logging in with a Master Password. Your login flow in commander will follow the same rules you have for logging into the Vault.
Login Example (2FA):
Not logged in> login
... User(Email): [email protected]
Logging in to Keeper Commander
This account requires 2FA Authentication
U2F (FIDO Security Key)
Send SMS Code
3. TOTP (Google Authenticator) [ ENABLED ]
DUO
Selection:
Each 2FA method that is enabled will have a number next to it.
In this example, only TOTP is enabled, so 3 would need to be entered, followed by the TOTP code. Enter the corresponding number to proceed:
Selection: 3
Enter 2FA Code or Duration: 2fa_duration=forever
Enter 2FA Code or Duration: 123456
By default, Keeper Commander prompts for 2FA code on every login. To store 2FA authentication for this device either for 30 days or forever, type one of the following before entering the code:
  • 2fa_duration=30_days to prompt for 2FA every 30 days, or...
  • 2fa_duration=forever to never prompt again on this device

Logging in with a Proxy

If your network configuration requires using a proxy server you can use the proxy command before logging in.
My Vault> proxy -h
usage: proxy [-h] [-a {list,add,remove}] [schema://[user:[email protected]]host:port]
Sets proxy server
positional arguments:
schema://[user:[email protected]]host:port
"add": proxy address. Schemas are "socks5h", "http", "socks4", etc
optional arguments:
-h, --help show this help message and exit
-a {list,add,remove}, --action {list,add,remove}
action

Enterprise SSO Login

If SSO is configured for your Keeper enterprise, the following screen will appear for users that login to Commander:
Not logged in> login
... User(Email): [email protected]
Logging in to Keeper Commander
SSO Login URL:
https://keepersecurity.com/api/rest/sso/saml/login/14955076124680?payload=XXXX
Navigate to SSO Login URL with your browser and complete login.
Copy a returned SSO Token into clipboard.
Paste that token into Commander
a. SSO User with a Master Password
c. Copy SSO Login URL to clipboard
o. Navigate to SSO Login URL with the default web browser
p. Paste SSO Token from clipboard
q. Quit SSO login attempt and return to Commander prompt
Selection:
To login to Commander using SSO, you will need to paste a token provided by the SSO provider in a browser into Commander. To receive the SSO token, follow these steps:

1. Open the SSO Login Screen in a Browser

There are several ways to open the SSO Connect screen in a browser:
Option 1: Open the Page Automatically From Commander
To have Commander automatically open the default browser to the SSO Connect page, enter "o" in the SSO selection and hit Enter
The default browser for your system will open to the SSO Connect page.
Depending on your operating system, settings, and administrator privileges, Commander may be unable to open the web browser, in this case use the following option to open the SSO Connect screen.
Option 2: Paste the SSO Login Screen URL into a Browser
You can copy the URL to your SSO's logins screen from the SSO Connect text in Commander, or enter "c" in the SSO selection and hit Enter to copy the URL to your clipboard.
SSO Login URL:
https://keepersecurity.com/api/rest/sso/saml/login/14955076124680?payload=XXXX
Once the URL is copied, paste it into a web browser to navigate to the SSO Connect page.

2. Paste Token into Commander

After a successful SSO login, the web page will show a yellow "Copy" button. Click the button to copy the token.
SSO Login success screen
Once the token has been copied, go back to Commander to complete the SSO login.
In Commander enter "p" in the SSO selection screen and hit Enter to paste the token from your clipboard into Commander and complete SSO login.
What if There is No "Copy login token" Button?

Device Approval with SSO Login

If device approval is turned on for your account, the device approval selection will be shown after the first SSO login.
Approve this device by selecting a method below:
1. Keeper Push. Send a push notification to your device.
2. Admin Approval. Request your admin to approve this device.
r. Resume SSO login after device is approved.
q. Quit SSO login attempt and return to Commander prompt.
Selection:
Enter your selection and hit Enter to continue with device approval.
1 : Approve with Keeper Push
2 : Approve with Admin Approval
r : Resume SSO login after the device has been approved
See First Login on a New Device section for more details on device approval.

Use a Master Password with SSO Login

Customers who normally login to their Keeper Vault using Enterprise SSO Login (SAML 2.0) can also login to Keeper Commander using a Master Password. To make use of this capability, it must be enabled by the Keeper Administrator and then configured by the user. The steps are below:
(1) Login to the Admin Console
(2) Enable SSO Master Password Policy
For the User/Role who will be accessing Keeper Commander, open the Role Enforcement Policy setting screen. Enable the option "Allow users who login with SSO to create a Master Password"
SSO Master Password Policy
(3) Login to the End-User Vault using SSO
US GovCloud Data Center: https://govcloud.keepersecurity.us/vault
(4) Create a Master Password
Visit the Settings > General screen and setup a Master Password
After the Master Password is created, you are now able to login to Keeper Commander.

Commander Configuration File

When you login to Commander for the first time, a config.jsonfile is created, if one does not exist. When launching Commander as an application, the config file is created at ~/.keeper on MacOS and Linux, and at C:\Users\[USERNAME]\.keeper on Windows. When using Commander from the command line or terminal, the config.json file is created in the current directory, unless the --config option is passed a different location.

Config File Example

{
"server": "keepersecurity.eu",
"user": "[email protected]",
"password": "your_password_here",
"private_key": "yaeK4jMeIGNkSR2pi4xf2XGmYM094YMUoE8-QEW9CAA",
"device_token": "g6RDMxr1t-bcVdBeBpz-xQ",
"mfa_duration": "forever",
"proxy": "http://proxy_user:[email protected]:port",
"sso_master_password": false,
"skip_records": false,
"debug": false,
"plugins": [],
"commands": [],
"timedelay": 0
}

Config File Options

  • server Keeper data center region
    Commander defaults to the US region, so customers hosted in other regions will need to specify a server in the config.
    Region
    Property Setting for "server"
    US
    https://keepersecurity.com
    EU
    https://keepersecurity.eu
    AU
    https://keepersecurity.com.au
    GOV
    https://govcloud.keepersecurity.us
  • debug enable or disable detailed crypto and network logging
    • set to true or false
  • plugins Set which password rotation plugin will be loaded.
    • Learn more about password rotation plugins for Commander.
  • commands Comma-separated list of Keeper commands to run
  • timedelay Run the specified commands every X seconds.
    • example: "timedelay":600 will run the commands every 10 minutes.
  • private_key Device private key generated by Commander on a new device. This key is used to encrypt and decrypt vault data.
  • device_token Device token generated by the backend for every new device. The device token is used to uniquely identify the device, and it controls the session behavior.
  • proxy Proxy URL: schema://[user:[email protected]]host:port where schema
    • http HTTP proxy
    • socks5 SOCKS5 proxy with local DNS
    • socks4 SOCKS4 proxy with local DNS
    • socks4a SOCKS4 proxy with remote DNS
    • socks5h SOCKS5 proxy with remote DNS
  • sso_master_password Forces master password login for Enrerprise SSO Accounts
  • skip_records Prevents syncing of records if the value is set to true. For users with very large vaults, this allows you to login and perform commands without requiring a full sync of records. After login, to force sync records use sync-down --force Example line in config.json: "skip_records":true,

Running Commands from the Configuration File

Using the commandsfield allows for predetermined commands to be run on login.
Enter a comma-separated list of Keeper Commander commands to be run. Example:
config.json
{
...
"commands": ["sync-down", "file-report -d"]
...
}
In this example, it will sync, and then download a report of the available files in the vault.

Configuration File Location

If you start Commander from the binary installer, the config file will be located in the user's home directory in a folder called ".keeper".
  • On Mac environments, the configuration file is located in ~/.keeper/config.json
  • In Windows environments, the configuration file is located in /Users/{Username}/Documents/.keeper/config.json
If you use Commander from a PIP3 or source installation, the configuration file will be created in the current folder where the Commander executable is started from.
You can specify the config file to use when launching Commander, for example:
$ keeper shell --config /path/to/config.json

Authenticating on Multi-Server Environments

In an environment with multiple servers or dynamic servers, you can use the same config.json file for each instance as long as all of the fields are populated, and the device identifier has been "approved".
Example config.json file:
{
"user": "[email protected]",
"password": "RANDOM_LONG_PASSWORD",
"server": "https://keepersecurity.com",
"private_key": "yaeK4jMeIGNkSR2pi4xf2XGmYM094YMUoE8-QEW9CAA",
"device_token": "g6RDMxr1t-bcVdBeBpz-xQ"
}
As long as you have performed a device approval step at least one time, this configuration file can be loaded on any number of servers.
If you plan to distribute this file to multiple instances, we recommend protecting this file through secure storage facilities provided by your cloud infrastructure. We also recommend assigning the user account to a Role Enforcement policy on the Keeper Admin Console that is locked down based on IP range.

Persistent Login Sessions

Persistent Login allows a Commander device to authenticate to Keeper without having to populate the "password" in the configuration file. This is useful for automation scripts or calling Commander from other software.
In order to enable this feature, you need to register the device and turn on the persistent login setting. Once that's done the next time you login with the specified configuration file, the session will be resumed and the user will be automatically logged in. Several tokens are stored in the config.json file in order to resume a session automatically.

Creating a Persistent Login Config

Commands to enable persistent login on a device for 365 days (max):
My Vault> this-device register
My Vault> this-device persistent-login on
My Vault> this-device ip-auto-approve on
My Vault> this-device timeout 365d
My Vault> quit
You can use seconds as the value (e.g. 60 for 60 seconds) or numbers and letters (e.g. 1m for one minute, 5h for 5 hours, and 7d for 7 days).
Also note that typing "logout" will invalidate the session. Just "quit" the Commander session to exit.
Once persistent login is set up on a device, the config.json in the local folder will look something like this:
{
"private_key": "8n0OqFi9o80xGh06bPzxTV1yLeKa5BdWc7f7CffZRQ",
"device_token": "R2O5wkajo5UjVmbTmvWnwzf7DK1g_Yf-zZ3dWIbKPOng",
"clone_code": "retObD9F0-WDABaUUGhP0Q",
"user": "[email protected]",
"server": "keepersecurity.com"
}
The configuration file can be modified to include auto-execution of commands or other features. See the configuration documentation for more details.
You can create any number of persistent login sessions. However, the persistent session option is not intended for dynamic multi-server environments. If you share the exact configuration file on multiple servers, persistent login will fail when attempting to login to the second server.
For multi-server dynamic environments, please refer to the prior section of using a fully populated config file that is distributed to each instance.

Executing Commands with Persistent Login

If you would like to maintain different configurations, you can run Commander with a specified config file. For example, this will open the CLI without prompting for login:
$ keeper --config=my_config.json shell
To leave the CLI, make sure to type "quit" instead of "logout". Typing "logout" will expire the session and you'll need to create a new persistent session config.
Another example would be executing a particular command without prompting for login. In the below example, a new record is created automatically with a single line.
$ keeper --config=config_demo.json "add --login myuser -g --url https://google.com -t 'Google'"

Batch Mode through STDIN

You can batch execute a series of commands and pipe the file to STDIN of Commander. For example, create a text file called test.cmd with the following lines:
add [email protected] --pass=somemasterpass --url=https://google.com --force "Some Record Title"
upload-attachment --file="/path/to/some/file.txt" "Some Record Title"
share-record --email="[email protected]" --write "Some Record Title"
To run this file in a batch mode:
cat test.cmd | keeper --batch-mode -
or
keeper test.cmd
Handling Errors
The batch execution is aborted if some command returns failure. Use @ in front of the command to suppress the possible command error.
add [email protected] --pass=somemasterpass --url=https://google.com --force "Some Record Title"
@upload-attachment --file="/path/to/some/file.txt" "Some Record Title"
share-record --email="[email protected]" --write "Some Record Title"
Batch Mode in Windows
Following example shows how to execute three commands using Windows command line:
(echo ls -l && echo whoami && echo tree) | keeper --batch-mode -

Combining Batch Mode and Persistent Login

By setting up a persistent login configuration (as described in the previous section), you can execute a series of batch commands without any prompt for login. For example:
$ keeper --config=my_config.json bunch_of_commands.cmd

Batch Mode from the CLI

Keeper supports a batch mode from within the CLI which can conveniently execute commands sequentially.
The command is called "run-batch" and can be executed like below:
My Vault> run-batch -d 10 "C:\My Drive\Keeper\commands.txt"
In this example, each command is executed with a delay of 10 seconds in between.
On Linux environments, the path can also be specified such as:
My Vault> run-batch -d 5 "/path/to/file.txt"

Video Overview

Watch the video below to learn more about accessing and working with your vault.
Keeper Commander – Accessing and Working with Your Vault