Using templates

One of the most powerful features of this command is that the YAML configuration files are treated as Jinja2 templates, allowing you to parametrize the synchronized files. For example, imagine a simple chart like this:

slice_name: Total sales
viz_type: big_number_total
params:
  metric: sum__sales
  adhoc_filters: []

The chart shows the metric sum__sales, representing the total (unfiltered) sales of a given product. We can change the chart configuration to look like this instead:

{% if country %}
slice_name: Sales in {{ country }}
{% else %}
slice_name: Total sales
{% endif %}
viz_type: big_number_total
params:
  metric: sum__sales
  {% if country %}
  adhoc_filters:
    - clause: WHERE
      expressionType: SQL
      sqlExpression: country = '{{ country }}'
      subject: null
      operator: null
      comparator: null
  {% else %}
  adhoc_filters: []
  {% endif %}

Now, if the country parameter is set the chart will have a different title and an additional filter. Multiple parameters can be passed as optiona via the command line:

% preset-cli --workspaces=https://abcdef12.us1a.app.preset.io/ \
> superset sync native /path/to/directory/ -o country=BR

Templates also have access to the workspace name through the instance variable (a URL object):

params:
  metric: sum__sales
  adhoc_filters:
    - clause: WHERE
      expressionType: SQL
      {% if instance.host == '//abcdef12.us1a.app.preset.io/ %}
      sqlExpression: warehouse_id = 1
      {% elif instance.host == '//34567890.us1a.app.preset.io/ %}
      sqlExpression: warehouse_id = 2
      {% else %}
      sqlExpression: warehouse_id = 3
      {% endif %}

You can also load variables from the environment by passing the --load-env (or -e) flag:

database_name: Postgres
sqlalchemy_uri: postgres://{{ env["POSTGRES_HOSTNAME"] }}

Finally, as shown in the next section, templates can leverage user-defined functions.

User defined functions

You can create your own functions to be used in the configuration templates. Simply create a sub-directory called functions/ in the directory where the configuration files are stored, and add one or more Python files. As a simple example, imagine a file called functions/demo.py with the following content:

# functions/demo.py
def hello_world() -> str:
    return "Hello, world!"

The function can then be called from any template the following way:

slice_name: {{ functions.demo.hello_world() }}
viz_type: big_number_total
params:
  ...

Disabling Jinja Templating

Both the CLI and Superset support Jinja templating. To prevent the CLI from loading Superset Jinja syntax, the export operation automatically escapes Jinja syntax from YAML files. As a consequence, this query:

sql: 'SELECT action, count(*) as times
    FROM logs
    {% if filter_values(''action_type'')|length %}
        WHERE action is null
        {% for action in filter_values(''action_type'') %}
            or action = ''{{ action }}''
        {% endfor %}
    {% endif %}
    GROUP BY action'

Becomes this:

sql: 'SELECT action, count(*) as times
    FROM logs
    {{ '{% if' }} filter_values(''action_type'')|length {{ '%}' }}
        WHERE action is null
        {{ '{% for' }} action in filter_values(''action_type'') {{ '%}' }}
            or action = ''{{ '{{' }} action {{ '}}' }}''
        {{ '{% endfor %}' }}
    {{ '{% endif %}' }}
    GROUP BY action'

When performing the import, the CLI would load any templating syntax that isn’t escaped, and remove escaping. However, this escaping syntax isn’t compatible with UI imports. To avoid issues when running migrations using both the CLI and the UI, you can use:

• --disable-jinja-escaping flag with the export-assets command to disable the escaping (so that exported assets can be imported via the UI)

• --disable-jinja-templating flag with the sync native command to disable jinja templating (so that assets exported via the UI can be imported via the CLI)

Note that using these flags would remove the ability to dynamically modify the content through the CLI.

Selecting models

By default all the models will be synchronized to the workspace. The CLI supports a subset of the syntax used by the dbt command line to select which models should be synchronized. Models that should be synchronized can be specified via the --select flag:

% preset-cli ... --select my_model    # sync only "my_model"
% preset-cli ... --select my_model+   # sync "my_model" and its children
% preset-cli ... --select my_model+2  # sync "my_model" and its children up to 2 degrees
% preset-cli ... --select +my_model   # sync "my_model" and its parents
% preset-cli ... --select +my_model+  # sync "my_model" with parents and children

Multiple selectors can be passed by repeating the --select flag (note that this is slightly different from dbt, which doesn’t require repeating the flag):

% preset-cli ... --select my_model --select my_other_model

The CLI also support the intersection operator:

% preset-cli ... --select my_model+,tag:test

The command above will synchronize my_model and its children, as long as the models have the “test” tag.

Finally, the CLI also supports the --exclude flag in a similar way:

% preset-cli --select my_model+ --exclude tag:test

The command above synchronizes “my_model” and its children, as long as the models don’t have the “test” tag.

Exporting users

The preset-cli superset export-users command can be used to export a list of users. These users can then be imported to Preset via the preset-cli import-users command.

Exporting roles

You can export roles via preset-cli superset export-roles, and import with import-roles.

Dataset permissions in new role exports include database, catalog, schema, and table names, so importing into another instance does not rely on local dataset IDs. For example:

permissions:
  - dataset access on [analytics].[warehouse].[public].[orders]
  - dataset access on [analytics].[].[public].[customers]

The four path components are always present. Empty brackets represent a missing catalog or schema. Dots inside brackets are part of the name; a closing bracket inside a name is escaped as ]]. Import resolves the complete path against the target dataset metadata. Multiple datasets with an identical complete path are ambiguous and fail the role import before its permissions or memberships change. Resolved permission IDs are deduplicated.

Qualified dataset grants require a CLI version that supports this format on import. Older CLI versions may silently omit these grants, so upgrade pinned CI jobs and other import clients before using new exports. dataset access is a portable role-file reference resolved by this CLI, rather than a native Superset permission name; other tools consuming these files must support it as well.

An empty catalog is matched literally, not as a wildcard. Superset versions before catalog support export paths such as [database].[].[schema].[table]. If the target uses a default catalog, update the YAML explicitly, for example to [database].[catalog].[schema].[table]. Re-exporting from the same older server cannot supply this missing catalog. Bulk edits should preserve the intended database, schema, and table identities.

Role files describe the complete intended permissions and memberships. All requested permissions must resolve on the target; a missing or ambiguous grant fails that role before it is created or updated. Unknown users and groups also fail the role. Legacy Superset imports reject nonempty group assignments because the legacy interface cannot apply them. Omitting groups means an empty list.

When migrating to Preset, action permissions are an explicit exception: they are skipped with warnings because Data Access Roles cannot represent them. Custom roles with only action grants are imported as empty Data Access Roles with a warning, since they can still be used for RLS or asset access. Built-in roles with data grants are imported with the _Preset suffix; built-ins without data grants are skipped. Missing data grants fail even for built-in roles.

If a previously imported <name>_Preset DAR exists when its source built-in has no data grants, the skip leaves that DAR’s permissions and memberships in place. The warning identifies this retained access; explicitly update or delete the mapped DAR to revoke it. A file containing both a built-in and its mapped name (for example, Gamma and Gamma_Preset) is rejected before any import writes, including with --continue-on-error.

By default, import-roles stops at the first failed role. With --continue-on-error, it records the failure and attempts the remaining roles, then exits nonzero if any role failed. These validation errors follow the same policy as API errors. Successful roles from earlier in the run are not rolled back; Superset REST permission, user, and group updates use separate requests, so an API failure during those writes can leave a role partially updated.

Within one import-roles run, the command prepares shared target lookups and passes them into each role import. Permissions, role names, users, groups, and resolved dataset names are reused. User and group listings are read only when memberships are requested; empty lists still clear existing memberships. Role indexes track successful writes, including creation before a later relationship update fails. Independent runs fetch fresh reference data.

Standalone Superset imports read security/permissions-resources before selecting the REST implementation. A 404 during permission or role-search detection selects the legacy HTML interface. Authentication, authorization, and server errors fail the role. Errors during REST writes never retry via HTML.

Older role files remain readable. Their datasource access permissions lack schema/catalog identity and use database/table-name matching with a warning; ambiguous matches fail. If an older Superset server cannot expose dataset metadata, export retains this legacy format and logs a warning. Importing the new qualified format requires target dataset metadata and never falls back to table-name matching. Re-export older files where metadata is available to obtain qualified paths.

Missing or stale target dataset-permission candidates are ignored when resolving qualified paths; the requested grant still fails if no verified full-path match exists, or if multiple permission IDs match. Dataset metadata is fetched in batches; when an older server ignores the ID filter and returns unrelated IDs, the complete response is reused instead of repeating the full scan per batch. Incomplete dataset metadata is a contract error and fails export rather than silently dropping path information. Roles are fetched and serialized before the output file is opened, preserving an existing file if preparation fails.

Schema permissions must match the target exactly. Older Superset exports use schema access on [database].[schema]; catalog-aware targets may instead use schema access on [database].[catalog].[schema]. Unmatched schema permissions fail the role import before any permissions or memberships are changed. Update the YAML to specify the intended target catalog explicitly; import never guesses the catalog or expands a schema grant across catalogs.

Action permissions can also change between Superset versions. An OSS-to-OSS import fails if the target no longer supports a permission declared in the YAML; remove or update that grant explicitly rather than expecting it to be skipped.

Exporting RLS rules

The preset-cli superset export-rls command can be used to export a list of RLS rules. Currently there’s no way to import this into a workspace, but work is in progress.

Exporting ownership

The preset-cli superset export-ownership command generates a YAML file with information about ownership of different resources. The file maps resource UUIDs to user email address, and in the future will be used to recreate ownership on a different instance of Superset.

Listing SCIM Groups

The preset-cli list-group-membership command prints all SCIM groups (including membership) associated with a Preset team. Instead of printing the results on the terminal (whcih can be useful for quick troubleshooting), it’s possible to use --save-report=yaml or --save-report=csv to write results to a file. The file name would be {TeamSlug}__user_group_membership.{FileExtension}.