💻 Using the CLI

The Supersimple CLI offers convenient tools to validate & import your data models.

Installation

The Supersimple CLI can be installed in different ways depending on your operating system and preferences.

macOS

Download the CLI for macOS:

• Apple Silicon
• Intel

Alternatively, macOS users can install the CLI using Homebrew:

brew tap gosupersimple/cli
brew install supersimple

Linux

Download the CLI for Linux.

Windows

Windows users can set up the CLI by installing the Linux version with WSL (Windows Subsystem for Linux). Once WSL is configured, follow the Linux installation instructions above.

TIP

After installing the CLI, make sure to include it in your PATH. Here's an example to get you going, but your setup might require something more permanent (e.g. updating your ~/.profile, ~/.bashrc or similar config file)

export PATH=$PATH:~/path/to/supersimple-cli

TIP

If the CLI notifies you about an upgrade being available, it can be downloaded via the same link.

If you installed via Homebrew, you can upgrade with:

brew update
brew upgrade supersimple

Setup

Create a .env file in your project's root directory and add the following environment variables:

.env

export SUPERSIMPLE_TOKEN='<token>'
export SUPERSIMPLE_ACCOUNT_ID='<account_id>'
export SUPERSIMPLE_HOST='https://app.supersimple.io'

Visit the account settings page to generate the token and find your account ID. Because this file contains sensitive credentials, make sure to add it to your .gitignore file.

Before running any commands, make sure to load in the environment variables by running:

source .env

Congratulations! You're now ready to use the CLI.

Commands

For a list of available commands, the CLI's installed version, etc.

supersimple --help

Each command also exposes their own --help option, for example

supersimple import --help

Validating models

supersimple validate config.yaml

If your models are split between multiple files, you can pass all of them to validation

supersimple validate config_a.yaml config_b.yaml

If you remove any existing models from your configuration, they won't get automatically deleted from Supersimple. You can check if you have any such "dangling" models with the following flag. You can then delete them during import by passing a --delete-dangling flag (see below).

supersimple validate config.yaml --validate-dangling

Importing

Use the Supersimple API to upload a new version of your data models. Even though your configuration can be split into multiple files, they'll need to be imported all at once to validate their integrity and relations.

supersimple import config.yaml # OK for a single-file setup

# bad in case of multiple files
supersimple import config_a.yaml
supersimple import config_b.yaml

# good for a multi-file setup
supersimple import config_a.yaml config_b.yaml

Dangling objects can be deleted automatically during import with the --delete-dangling flag

supersimple import config.yaml --delete-dangling

Autofix

To detect missing relations between models, use the fix command.

supersimple fix config.yaml

The output of the fix command can be printed as YAML:

supersimple fix --format=yaml config.yaml

When feeling lucky, you can overwrite your configuration file in-place:

supersimple fix --format=yaml config.yaml > tmp.$$; mv tmp.$$ config.yaml

Discovery

The CLI has commands to generate models from existing database schema. It creates one data model per database table and generates relations between them when specified in database schema. Discovery outputs YAML that can be imported to Supersimple by using the import command.

To include only specific tables, use comma separated list of table names with --tables tableA,tableB option. Similarly, tables can be excluded from discovery with --skip-tables tableX,tableY option.

Postgres

supersimple discover postgres models \
  --url <DATABASE_URL> > supersimple.yaml

Optionally, you can specify Postgres database schema using the --schema option.

Discover all possible values for enum column:

supersimple discover postgres enum
  --url <DATABASE_URL> --table <table> --column <column>

Optionally, you can specify label for the enum option by using --label-column option.

BigQuery

List datasets:

supersimple discover bigquery datasets \
  --credentials <path_to_credentials.json>

Discover models and store them in supersimple.yaml:

supersimple discover bigquery models \
  --credentials <path_to_credentials.json> \
  --project <project> \
  --dataset <dataset> \
  > supersimple.yaml

Discover all possible values for enum column:

supersimple discover bigquery enum
  --credentials <path_to_credentials.json> \
  --project <project> \
  --dataset <dataset> \
  --table <table> --column <column>

Optionally, you can specify label for the enum option by using --label-column option.