The Supernova command-line interface (CLI) enables you to run specific tasks connected with Supernova from your CI/CD pipelines, from your action triggers (GitHub Actions and similar) or from your command line as well. The Supernova CLI is powered by the Supernova SDK, which allows access to many lower-level operations.
Here you will find a repository that automatically syncs Figma Tokens through GitHub Actions to Supernova.io when token data changes, and is a great example of fully automated synchronization between Figma Tokens and Supernova.
The synchronization is done through GitHub Actions that run every time a new token file (or files) is committed into this repository. It uses the Supernova CLI to facilitate the synchronization routine.
Setting up the CLI
There are a few things required to set up the CLI.
Set up the GitHub integration inside Token Studio
To set up, you'll need to provide:
- A name
- A personal access token (github profile -. dev setttings -> personal access token)
- A repository
- A file path
Then make sure to save this information by clicking Save credentials.
Change the supernova.settings.json file in the repository
In order to set up the integration with the CLI, you now need to configure the mapping.
Because token structures within both Figma Tokens and Supernova can be very complex, you must clearly describe your intention as to how to map the data from one place to the other.
You must do so by providing a configuration JSON file called supernova.settings.json containing all of the mapping. Here is an example how your settings file can look:
{
"mode": "single-file",
"mapping": [{
"tokensTheme": "Light",
"supernovaBrand": "Default",
"supernovaTheme": null
},
{
"tokensTheme": "Dark",
"supernovaBrand": "Default",
"supernovaTheme": "Dark"
}
],
"settings": {
"dryRun": false,
"verbose": false,
"preciseCopy": false
}
}
Below you can see the explanation for every configuration option presented above.
- Mode → Signifies synchronization mode. Use single-file for syncing from a single file, and multi-file for syncing from a directory.
- Mapping → Mapping is an Array of rules on how to map data from Figma Tokens to Supernova. It can be translated as this: "Take all the tokens from Figma Tokens included in the theme "Brand A - Light" and sync them with Supernova brand "default", under token theme "Dark theme". You can define as many of those combinations as you want in the settings file.
- Token sets → If you are not using themes, you can select a combination of sets to use as data. You can select as many sets as you want, similarly how you select them within the Figma Tokens plugin itself. Fill tokenSets with Array of names of sets you have defined within Figma Tokens plugin. You can use as many sets as you want per each mapping.
- Supernova brand → Signifies the Supernova brand you want to sync data with, corresponds to supernovaBrand, and is required. Both brand name or brand ID are valid value options.
- Supernova theme → If you are using themes, you can select a specific theme to use as data. You can select exactly one theme per mapping. Fill tokensTheme with the name or ID of Figma Tokens theme you would liek to write to Supernova.
Settings -> Changes how the synchronization behaves. The following attributes are available:
- dryRun (optional, default: false) allows you to test your synchronization without actually writing to the workspace. We recommend enabling this option while you are configuring your setup.
- verbose (optional, default: false) allows you to get detailed log of what is happening with your data, such as how many tokens were updated, deleted, etc.
- preciseCopy (optional, default: false) allows you to synchronize tokens fully.
Once the mapping and configuration is done as explained above and you decide to fork our repository, you will have to make some adjustments in regard to the YML file.
The only thing that you will have to change is the last part. This last specific part points to the specific configuration for this repository.
supernova sync-tokens
--apiKey="${{ secrets.SN_ACCESS_TOKEN_FTP }}"
--designSystemId="24880"
--tokenFilePath "${{ github.workspace }}/test2/tokens.json"
--configFilePath "${{ github.workspace }}/test2/supernova.settings.json"
As you can see, there is an API key. It is written as a secret and there is a specific way to do it:
Repository -> Settings -> Secrets and variables -> Actions -> New repository secret -> Add secret
Provide the Supernova CLI with an API key
You can obtain API key from your Supernova profile. We strongly recommend keeping your API key in secure storage, either through use of environment variables or key vault if you are using services like GitHub (Actions). Never share your API key with anyone!
Use your newly obtained key as the value of the --apiKey attribute.
For sync to work, you also need to obtain the ID of Supernova design system you want to target. Go to your design system and anywhere, in any section, obtain the ID from the URL of your browser. Make sure you have selected the correct design system before copying the ID.
Use your newly obtained key as the value of --designSystemId attribute.
And the last step, depending on your choice in step #1, fill --tokenFilePath or --tokenDirPath with the path (relative or absolute) to your Figma Token definitions. For single-file mode, you must point to a file path of JSON containing all tokens, for multi-file mode, you must point to a directory with JSON file definition. You can only provide one option at a time.
Run the sync and let the magic happen!