Get started with the Code42 command-line interface (CLI)

Licensing

This project uses the MIT License.

Installation

You can install the Code42 CLI from PyPI, from source, or from distribution.

From PyPI

The easiest and most common way is to use pip:

python3 -m pip install code42cli

To install a previous version of the Code42 CLI via pip, add the version number. For example, to install version 0.5.3, enter:

python3 -m pip install code42cli==0.5.3

Visit the project history on PyPI to see all published versions.

From source

Alternatively, you can install the Code42 CLI directly from source code:

git clone https://github.com/code42/code42cli.git

When it finishes downloading, from the root project directory, run:

python setup.py install

From distribution

If you want create a .tar ball for installing elsewhere, run the following command from the project’s root directory:

python setup.py sdist

After it finishes building, the .tar ball will be located in the newly created dist directory. To install it, enter:

python3 -m pip install code42cli-[VERSION].tar.gz

Updates

To update the CLI, use the pip --upgrade flag.

python3 -m pip install code42cli --upgrade

Authentication

Important

The Code42 CLI currently only supports token-based authentication.

Create a user in Code42 to authenticate (basic authentication) and access data via the CLI. The CLI returns data based on the roles assigned to this user. To ensure that the user’s rights are not too permissive, create a user with the lowest level of privilege necessary. See our Role assignment use cases for information on recommended roles. We recommend you test to confirm that the user can access the right data.

If you choose not to store your password in the CLI, you must enter it for each command that requires a connection.

The Code42 CLI supports local accounts with MFA (multi-factor authentication) enabled. The Time-based One-Time Password (TOTP) must be provided at every invocation of the CLI, either via the --totp option or when prompted.

The Code42 CLI currently does not support SSO login providers or any other identity providers such as Active Directory or Okta.

Windows and Mac

For Windows and Mac systems, the CLI uses Keyring when storing passwords.

Red Hat Enterprise Linux

To use Keyring to store the credentials you enter in the Code42 CLI, enter the following commands before installing.

yum -y install python-pip python3 dbus-python gnome-keyring libsecret dbus-x11
pip3 install code42cli

If the following directories do not already exist, create them:

mkdir -p ~/.cache
mkdir -p ~/.local/share/keyring

In the following commands, replace the example value \n with the Keyring password (if the default Keyring already exists).

eval "$(dbus-launch --sh-syntax)"
eval "$(printf '\n' | gnome-keyring-daemon --unlock)"
eval "$(printf '\n' | /usr/bin/gnome-keyring-daemon --start)"

Close out your D-bus session and GNOME Keyring:

pkill gnome
pkill dbus

If you do not use Keyring to store your credentials, the Code42 CLI will ask permission to store your credentials in a local flat file with read/write permissions for only the operating system user who set the password. Alternatively, you can enter your password with each command you enter.

Ubuntu

If Keyring doesn’t support your Ubuntu system, the Code42 CLI will ask permission to store your credentials in a local flat file with read/write permissions for only the operating system user who set the password. Alternatively, you can enter your password with each command you enter.

To learn more about authenticating in the CLI, follow the Configure profile guide.

Troubleshooting and support

Code42 command not found

If your python installation has added itself to your environment’s PATH variable, then running code42 should just work.

However, if after installation the code42 command is not found, the CLI has some helpers for this (added in version 1.10):

You can execute the CLI by calling the python module directly:

python3 -m code42cli

And the base code42 command now has a --script-dir option that will print out the directory the code42 script was installed into, so you can manually add it to your PATH, enabling the code42 command to work.

On Mac/Linux:

Run the following to make code42 visible in your shell’s PATH (to persist the change, add it to your shell’s configuration file):

export PATH=$PATH:$(python3 -m code42cli --script-dir)

On Windows:

$env:Path += ";$(python -m code42cli --script-dir)"

To persist the change, add the updated PATH to your registry:

Set-ItemProperty -Path 'Registry::HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Session Manager\Environment' -Name PATH -Value $env:Path

Debug mode

Debug mode may be useful if you are trying to determine if you are experiencing permissions issues. When debug mode is on, the CLI logs HTTP request data to the console. Use the -d flag to enable debug mode for a particular command. -d can appear anywhere in the command chain:

code42 <command> <subcommand> <args> -d

File an issue on GitHub

If you are experiencing an issue with the Code42 CLI, select New issue at the project repository to create an issue. See the Github guide on creating an issue for more information.

Contact Code42 Support

If you don’t have a GitHub account and are experiencing issues, contact Code42 support.

What’s next?

Learn how to Set up a profile.