Appearance
💻 Using the CLI
The Supersimple CLI offers convenient tools to validate & import your data models. To get started, you'll need an API token and the CLI itself. You can generate the token and install the CLI from your account settings page.
TIP
If the CLI notifies you about an upgrade being available, it can be downloaded via the same link.
Setup
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)
sh
export PATH=$PATH:~/path/to/supersimple-cli
Create a .env
file in your project's root directory and add the following environment variables:
sh
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:
sh
source .env
Congratulations! You're now ready to use the CLI.
Commands
For a list of available commands, the CLI's installed version, etc.
sh
supersimple --help
Each command also exposes their own --help
option, for example
sh
supersimple import --help
Validating models
sh
supersimple validate config.yaml
If your models are split between multiple files, you can pass all of them to validation
sh
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).
sh
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.
sh
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
sh
supersimple import config.yaml --delete-dangling
Autofix
To detect missing relations between models, use the fix
command.
sh
supersimple fix config.yaml
The output of the fix
command can be printed as YAML:
sh
supersimple fix --format=yaml config.yaml
When feeling lucky, you can overwrite your configuration file in-place:
sh
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
sh
supersimple discover postgres models --url <DATABASE_URL> > supersimple.yaml
Optionally, you can specify Postgres database schema using the --schema
option.
BigQuery
List datasets:
sh
supersimple discover bigquery datasets \
--credentials <path to credentials.json>
Discover models and store them in supersimple.yaml
:
sh
supersimple discover bigquery models \
--credentials <path to credentials.json> \
--project <project> \
--dataset <dataset> \
> supersimple.yaml