Connecting CLI to Astralis Cloud

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

This guide is for Astralis Cloud, hosted edition. For information about deploying Astralis to your own infrastructure, see the Installation guides.

We'll break this down into these steps:

Create and use a new Python virtual environment
Install Astralis CLI via pip
Connect your Astralis CLI to Astralis Cloud
Login to your Astralis Cloud instance

Let's get started!

Prerequisites

For this guide you'll need:

Python 3.10 installed locally (read more about version requirements)

Check that you have python3.10 installed and ready to use:

~% python3.10 --version
Python 3.10.13

This guide assumes you will use the python3.10 version explicitly, but if you manage your python versions differently (e.g. via pyenv), update the commands accordingly!

Create and use a new Python virtual environment

Since we'll be installing the Astralis 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.10 -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:

Example terminal prompt

(venv) ~/fides-cloud%

Install Astralis CLI via `pip`

Once you've setup your virtual environment, you can install the Astralis 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.57.0

ⓘ

If you have trouble with your Python installation, you're probably not alone! For help, ask in the Astralis Slack Community (opens in a new tab).

Connect your Astralis CLI to Astralis Cloud

Lastly, we need to connect your local CLI to your Astralis 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. astralis-example.us.astralis.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:

Example fides.toml config file

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

Next, we'll replace the <YOUR_FIDES_CLOUD_HOSTNAME> variable with your own Astralis Cloud hostname. For example, if you login at https://astralis-example.us.astralis.ethyca.com (opens in a new tab), your hostname is astralis-example.us.astralis.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 Astralis Cloud status with the fides status command and should see a success message similar to this:

Example success message

(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 Astralis Cloud! For more advanced information about the .fides/ directory, you can read about initializating working directories here.

Login to your Astralis Cloud instance

Lastly, you can login to your Astralis 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.

Example login

(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 Astralis CLI to your Astralis Cloud instance, and can now run all the local CLI commands to interact with the Astralis 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 Astralis 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

deploy annotate