Using the CLI

The Supersimple CLI offers convenient tools to validate, import & export your data models, metrics, and explorations.

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 and authentication

After installation, you'll need to connect the CLI to your Supersimple account.

The easiest way to authenticate with the Supersimple CLI is using the interactive login command:

supersimple login

This command will guide you through the authentication process and securely store your credentials.

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

Basic usage

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

Importing data models

To import data models to your Supersimple account (or to update existing data models), use supersimple import.

If your data models are split across multiple YAML files, you need to import them all at once to validate their integrity and relations.

Path arguments support glob patterns and directories, so you can point to an entire folder of YAML files.

# Import a single configuration file:
supersimple import config.yaml

# Import multiple configuration files:
supersimple import config_a.yaml config_b.yaml

# Import all YAML files in a directory:
supersimple import models/

# Import using glob patterns:
supersimple import models/*.yaml metrics/*.yaml

# Do NOT import multiple files using separate commands like so:
supersimple import config_a.yaml
supersimple import config_b.yaml

Dangling data models

If you want to make sure that no data models exist in your account other than the ones you're importing now, you can run the command with the --delete-dangling flag.

This cleans up any "dangling" data models that were previously synced, but are not present in your newly-imported model files.

supersimple import config.yaml --delete-dangling

Exporting configuration

supersimple export exports your existing models, metrics, and explorations from Supersimple to YAML files.

By default, it exports everything and writes individual files under models/, metrics/, and explorations/ subdirectories in the current directory.

# Export all models, metrics, and explorations:
supersimple export

# Export to a specific directory:
supersimple export -o my-config/

# Export only models:
supersimple export --models

# Export only specific entities by ID:
supersimple export --model-ids model_a,model_b --metric-ids metric_x

# Print to stdout instead of writing files:
supersimple export --stdout

# Overwrite existing files without asking:
supersimple export --force

When entity IDs are specified (via --model-ids, --metric-ids, or --exploration-ids), only those entities are exported. You can combine ID flags with type flags (e.g. --models) to include all entities of a given type alongside specific IDs of another type.

After exporting, you can edit the generated YAML files and re-import them using supersimple import to apply your changes.

This allows you to make changes to your configuration programmatically or using a code agent. You can also make backwards-incompatible changes in models and update the metrics and explorations that depend on them all in one go.

Discovery

Auto-generating data models

supersimple discover models auto-generates data model YAML files based on your database schema.

It creates one data model per database table and generates relations between them when specified in database schema.

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

supersimple discover models

By default, the command writes individual model files under a models/ subdirectory. To write to a different directory, use the -o flag:

supersimple discover models -o my-models/

Optionally, you can run discovery on a non-default database schema using the --schema flag (e.g. --schema myschema).

Other CLI commands

Validating configuration

While the import command does also run validation, it's often helpful to separately check that everything is OK with your configuration, without yet importing it in case of success.

The supersimple validate command checks that every model, metric, and exploration is properly configured, and that nothing is missing.

supersimple validate config.yaml

# Validate all files in a directory:
supersimple validate models/ metrics/

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. This will also output warnings if removing these models would break other models or explorations that are still dependent on them. Note that some of these warnings may have a shared root cause so its best to start addressing the affected models first and re-run the validation as you go.

You can then delete them during import by passing a --delete-dangling flag (see below).

supersimple validate config.yaml --validate-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