Connecting CLI to Fides Cloud

In this guide, we will setup the Fides CLI on your local machine and connect it to your Fides Cloud instance so that you can programmatically push & pull resources, evaluate privacy checks, and much more!

We'll break this down into these steps:

1. Create and use a new Python virtual environment
2. Install Fides CLI via pip
3. Connect your Fides CLI to Fides Cloud
4. Login to your Fides Cloud instance

Let's get started!

Prerequisites

For this guide you'll need:

• A Fides Cloud or Fides Enterprise account
• Python 3.9 or 3.10 installed locally (read more about version requirements)

Create and use a new Python virtual environment

Since we'll be installing the Fides CLI using the ethyca-fides (opens in a new tab) Python package, it's best practice to first create a new Python virtual environment to install into (read more about virtual environments here: Python Packaging User Guide (opens in a new tab)).

First, create a new project directory on your local machine where you'll setup your CLI. For this guide, we'll use a folder called ~/fides-cloud in your home directory like so:

mkdir ~/fides-cloud
cd ~/fides-cloud

Next, from within your project directory, create a Python virtual environment. For this guide, we'll call it venv:

python3 -m venv venv

Lastly, activate the new venv:

source venv/bin/activate

If everything worked correctly, you should see an indication in your terminal prompt like this:

(venv) ~/fides-cloud%

Install Fides CLI via pip

Once you've setup your virtual environment, you can install the Fides CLI via the ethyca-fides (opens in a new tab) Python package. Ensure you've activated your virtual environment (from the previous step) and then run pip:

pip install ethyca-fides

This will take a few minutes to download and install the various project dependencies. Once complete, you can use the fides --version command to test that everything is running as expected:

(venv) ~/fides-cloud% fides --version
fides, version 2.25.0

Connect your Fides CLI to Fides Cloud

Lastly, we need to connect your local CLI to your Fides Cloud instance. To do this, we'll create a minimal .fides/fides.toml configuration file and edit it accordingly.

First, run the following command from your ~/fides-cloud project directory:

mkdir .fides
cat > .fides/fides.toml << EOF
[cli]
server_host = "<YOUR_FIDES_CLOUD_HOSTNAME>" # e.g. fides-example.us.fides.ethyca.com
server_port = 443
server_protocol = "https"
EOF

This will create a new .fides/ working directory and initialize it with a minimal fides.toml configuration file that looks like this:

[cli]
server_host = "<YOUR_FIDES_CLOUD_HOSTNAME>" # e.g. fides-example.us.fides.ethyca.com
server_port = 443
server_protocol = "https"

Next, we'll replace the <YOUR_FIDES_CLOUD_HOSTNAME> variable with your own Fides Cloud hostname. For example, if you login at https://fides-example.us.fides.ethyca.com (opens in a new tab), your hostname is fides-example.us.fides.ethyca.com.

Once you've found your hostname, edit the config file with your favorite editor and save your changes:

open .fides/fides.toml

If you've done this successfully, you can check your Fides Cloud status with the fides status command and should see a success message similar to this:

(venv) ~/fides-cloud% fides status
> Loaded config from: .fides/fides.toml
Getting server status...
Server is reachable and the client/server application versions match.

Great, you've configured your fides CLI to connect to Fides Cloud! For more advanced information about the .fides/ directory, you can read about initializating working directories here.

Login to your Fides Cloud instance

Lastly, you can login to your Fides Cloud instance using the fides user login command. This authenticates your local CLI to allow you to make edits and changes to the server.

To authenticate, run the following command and follow the prompts to enter your username and password:

fides user login

If your credentials are correct, you should see a success message like the one below, and your credentials will be saved locally and used for future commands.

(venv) ~/fides-cloud% fides user login
> Loaded config from: .fides/fides.toml
Username: user@example.com
Password: 
Logged in as user: user@example.com
Credentials file written to: /Users/example/.fides_credentials

Congratulations! You've installed and connected the Fides CLI to your Fides Cloud instance, and can now run all the local CLI commands to interact with the Fides server.

As a next step, try running commands like fides ls system or fides ls dataset to view the System or Dataset resources you may have configured in Fides Cloud previously. Enjoy!

Optional: Reactivating Python virtual environment

For future CLI sessions, you'll need to reactivate the Python venv to run CLI commands. You can reactivate your virtual environment at any time by switching back to the project directory and running the activate command:

cd ~/fides-cloud
source venv/bin/activate
fides --version