The Preset CLI
  • 14 Jul 2023
  • 2 Minutes to read
  • Dark
    Light

The Preset CLI

  • Dark
    Light

Article summary

API Requirement

You need to have access to the Preset API in order to successfully use the Preset CLI.

Overview

The Preset CLI can be used to perform many tasks in Preset, such as:

  • Content migration (export and import) and management.
  • Running SQL queries.
  • Syncing models from dbt Core and dbt Cloud.
  • Team management.

Some functionalities work both for Preset and Superset. The structure to execute a command against a Preset Workspace would normally be:

preset-cli --workspaces=$workspace_url --$auth superset $command $args

Authentication can also be stored to a system file, so that it doesn't have to be included on every command.

The structure to execute a command against a Superset instance is usually:

superset-cli --$auth $superset_url $command $args

Installation

Use a Python Virtual Environment

It's strongly encouraged to install Python packages using Virtual Environments.

There are two ways possible sources to install the CLI:

  • From the Python Package Index (PyPI): This operation installs the latest version officially released of the package. To install it from PyPI, run:
    pip install preset-cli
    
  • From the Github repository directly: This would install the CLI containing latest bug fixes and new functionalities merged to the repository, that might haven't been officially included in a new release yet. To install it from the repository, run:
    pip install "git+https://github.com/preset-io/backend-sdk.git"
    

Authentication

In order to interact with your Workspaces, the CLI uses valid API token/secret to generate a jwt token and perform the desired actions. Make sure to use an account with proper permissions to generate the API. There are different mehtods to authenticate CLI commands:

Saving credentials in the system (Preset only)

Once the CLI is installed, you can run preset-cli auth to be prompted to provide your API token and secret. These values would be stored in a system-dependent location, in a file that's only readable by you.

Once credentials have been stored, running preset-cli auth would show an error including the path to the file created. If you need to replace credentials, run preset-cli auth --overwrite.

Providing the API Token and Secret directly in the command (Preset only)

Instead of locally saving your credentials, it's also possible to provide them directly in the desired command. For example:

preset-cli --api-token $my_api_token --api-secret $my_api_secret ...

This is specially useful in case you want to automate CLI actions (using Github actions, etc).

Providing username and password directly in the command (Superset only)

For Superset, it's possible to provide the username and password directly in the command. For example:

superset-cli -u $username -p $password ...

Providing the JWT token directly in the command

Lastly, it's also possible to use the Get a JWT Token API endpoint to generate the jwt, and then pass it directly in the CLI command. For example:

preset-cli --jwt-token $my_jwt ...

For Superset:

superset-cli --jwt-token $my_jwt ...

Suppported Commands

Team Operations

These are the supported features on the team level:

  • Export users
  • Import users
  • Invite users
  • List SCIM group memberships

You can find further details about these features in the Team Operations page.

Workspace Operations

These are the supported Workspace operations:

  • Export ownership (Superset only)
  • Export resoures
  • Export roles
  • Export RLS rules
  • Import ownership
  • Import resources
  • Import roles (Preset only)

You can find further details about these functionalities in the Workspace Operations page.

dbt Sync

  • Sync dbt models (including columns, metrics and metadata) to Preset as datasets.
  • Sync Preset charts and dashboards to dbt as exposures.

You can find further details about them in the dbt Sync page.


Was this article helpful?