Getting Started with the Praetorian CLI

Chariot functionality is accessible through our open-source command-line interface. The public GitHub repo can be found at https://github.com/praetorian-inc/praetorian-cli. Pre-built packages are officially hosted at https://pypi.org/project/praetorian-cli/. The most up to date information can always be found on the Readme page.

Before you can use the Praetorian CLI with your Chariot account, you will need to sign up through the UI. When you have your username and password, you can connect to your account through the CLI. Follow along for more instructions on how to do this.

Installation

Before you install the Chariot CLI, ensure you have Python 3.8 or higher and pip 23.0 or higher. Once you have the pre-requisites, head to your command-line interface and type:

pip install praetorian-cli

If you have previously installed the CLI, use the following to upgrade to the latest version:

pip install --upgrade praetorian-cli

To confirm that the installation was successful, you can type praetorian --version  into the command line. If the installation was successful you will see the current version displayed.

Authentication to Chariot

The CLI uses a keychain file to authenticate you to the system. To create the keychain file, you can run the command:

praetorian configure

When you run the command, you will be prompted with the following:

Enter your email:
Enter your password:
Enter the profile name [United States]:
Enter the URL of backend API[https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/chariot]:
Enter the client ID [795dnnr45so7m17cppta0b295o]:
Enter the assume-role account, if any[]:

1. The email and password refer to the same email and password that you use to log into the Chariot UI.
2. The profile name can be customized, but most users should press Enterand proceed with the default. 
3. The URL of the backend API and the client ID should remain as the defaults. Users should press Enter at these steps.
4. The assume-roll account, if someone else has invited you to their organization within the Chariot UI, you will add their account sign-in address here.

After entering all the appropriate values, the Praetorian CLI will read your keychain file from ~/.praetorian/keychain.ini. The keychain.ini file should read something like this when you are done:

[United States]
name = chariot
client_id = 795dnnr45so7m17cppta0b295o
api = https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/chariot
username = lara.lynch@acme.com
password = 8epu9bQ2kqb8qwd.GR

You can add multiple profiles to your keychain file, which takes a similar form to AWS CLI configuration files. For example: 

[United States]
name = chariot
client_id = 795dnnr45so7m17cppta0b295o
api = https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/chariot
username = lara.lynch@acme.com
password = 8epu9bQ2kqb8qwd.GR

[profile2]
...

[profile3]
...

Authentication in organizations that use SSO

SSO-enabled accounts can use the CLI by inviting password-based accounts as collaborators. These collaborator accounts can assume into the main account using the --account option in the CLI, or including that information in the keychain file. For example, you can assume into the security.team@acme.com main account using the account entry in the keychain file:

[United States]
name = chariot
client_id = 795dnnr45so7m17cppta0b295o
api = https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/chariot
username = lara.lynch@acme.com
password = 8epu9bQ2kqb8qwd.GR
account = security.team@acme.com

There are two common approaches to manage CLI access in SSO organizations:

1. Sign up a service account for CLI access: e.g. security.team+cli@acme.com. In the main account, invite security-team+cli@acme.com as a collaborator. All CLI users share the keychain of security-team+cli@acme.com.
2. Add each CLI user as a collaborator in the master account. Every CLI user signs up using password-based authentication.

We recommend the first approach.

We hope that this information has been helpful. Again, the most up to date information will be on the Readme page.

If you find a topic that you would like discussed in detail, or need further assistance, please let us know at support@praetorian.com!