Configuration
Understanding the Commander configuration file for automation and CLI usage
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.{
"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:proxy_password@host:port",
"sso_master_password": false,
"skip_records": false,
"debug": false,
"plugins": [],
"commands": [],
"timedelay": 0
}
serverKeeper data center regionCommander defaults to the US region, so customers hosted in other regions will need to specify a server in the config.RegionProperty Setting for "server"UShttps://keepersecurity.comEUhttps://keepersecurity.euAUhttps://keepersecurity.com.auGOVhttps://govcloud.keepersecurity.usCAhttps://keepersecurity.caJPhttps://keepersecurity.jpdebugenable or disable detailed crypto output and network logging- set to
trueorfalse
pluginsSet which password rotation plugin will be loaded.commandsComma-separated list of Keeper commands to runtimedelayRun the specified commands every X seconds.- example:
"timedelay":600will run the commands every 10 minutes.
private_keyDevice private key generated by Commander on a new device. This key is used to encrypt and decrypt vault data.device_tokenDevice 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.proxyProxy URL:schema://[user:password@]host:portwhere schemahttpHTTP proxysocks5SOCKS5 proxy with local DNSsocks4SOCKS4 proxy with local DNSsocks4aSOCKS4 proxy with remote DNSsocks5hSOCKS5 proxy with remote DNS
sso_master_passwordForces master password login for Enterprise SSO Accountsskip_recordsPrevents syncing of records if the value is set totrue. 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 usesync-down --forceExample line in config.json:"skip_records":true,
Using the
commands field 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.
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
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 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.Commands to enable persistent login on a device for 30 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 30d
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.
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'"
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 -
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
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"
The sensitive configuration file parameters (user, password, server, device_token, private_key, clone_code) can be optionally stored in 3rd party secrets managers or hardware security modules.
To use protected storage, add
config_storage property to your config file. config_storage value has URL format. Please reference the appropriate section below for storage URL format.Commander supports the following protected storages:
Last modified 2mo ago