@supernovaio/cli/README.md

Supernova.io Command Line Interface

<img src="https://github.com/Supernova-Studio/cli/blob/main/docs/images/cli.png?raw=true" alt="Supernova CLI" style="max-width:100%; margin-bottom: 20px;" />

# Supernova CLI [![All passing](https://img.shields.io/badge/Test-passing-success)]() [![CLI Status](https://img.shields.io/badge/CLI%20Status-Beta-blue)]() [![Version 0.9.13](https://img.shields.io/badge/Version-0.9.13-success)]()

The [Supernova](https://supernova.io) 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.

CLI is separated into different commands that you can use to automate certain aspects of working with Supernova. More command line options are coming as well, stay tuned for those!

### Installing CLI globally

You can also install the CLI as global package, and make the CLI globally available under `> supernova` command to your command line. To install the CLI globally, just run the following command:

```
npm install -g @supernovaio/cli
yarn global add @supernovaio/cli
```

You can now test that everything was properly set up by running the `supernova` command:

```
~ % supernova --version
> @supernovaio/cli/1.x.x ...
```

`Node 20` or newer environment is required to run the Supernova CLI.

### Updating CLI globally

You can update globally installed CLI by running npm update command on the package:

```
npm update -g @supernovaio/cli
yarn global upgrade @supernovaio/cli
```

This will upgrade the CLI to the latest version and make it immediately last default used version.

## Login Command

The login command is a crucial part of the Supernova CLI, as it establishes authentication required before using any other commands. This section explains how the login process works and how to use it effectively.

### Overview

The login command authenticates you with Supernova services using a secure OAuth flow with PKCE (Proof Key for Code Exchange). This authentication method is secure and follows modern best practices for CLI authorization.

```bash
supernova login
```

### How It Works

The login process follows these steps:

1. **Initiate Authentication**: The CLI generates a secure code challenge using PKCE.
2. **Browser Authentication**: Your default browser will open automatically to Supernova's authentication page.
3. **Authorization**: Complete the authentication in your browser.
4. **Token Storage**: Once authenticated, the CLI securely stores your tokens for future use.
5. **Completion**: You'll see a confirmation message when successfully logged in.

### Token Storage

Your authentication tokens are securely stored using one of the following methods:

1. **System Keychain** (Primary method): The CLI uses your operating system's secure credential store.
2. **Local File** (Fallback): If keychain access fails, tokens are stored in . `~/.supernova/tokens.json`
3. **Environment Variable**: You can bypass the login process by setting the environment variable. `SUPERNOVA_TOKEN`

### Automatic Token Refresh

The CLI automatically handles token refreshing:

- Tokens nearing expiration (within 5 minutes) are automatically refreshed.
- If a refresh token fails, you'll be prompted to log in again.

### Usage Examples

Standard login:

```bash
supernova login
```

### Troubleshooting

If your browser doesn't open automatically, the CLI will display a URL that you can manually copy and paste into your browser to complete the authentication process.
If you encounter authentication issues, you can try:

1. Running the login command again
2. Checking your internet connection
3. Ensuring you have the correct permissions in Supernova

### Important Notes

- You must complete the authentication process within 5 minutes (300 seconds)
- All other CLI commands will verify authentication before execution
- To log out, you can use the `logout` command (which removes stored tokens)

## Configuration File

The Supernova CLI supports configuration files to streamline your workflow by persisting command options and preferences.

### Overview

When working with Supernova CLI, you can use a configuration file named located in your current working directory. This file stores your command-specific options, eliminating the need to repeatedly provide the same flags and parameters in subsequent commands. `.supernova.json`

### File Structure

The configuration file uses a simple JSON structure:

```json
{
  "commands": {
    "command-name": {
      "option1": "value1",
      "option2": "value2"
    }
  },
  "global": {}
}
```

The file consists of two main sections:

- **commands**: Contains configurations for specific CLI commands, organized by command ID
- **global**: Reserved for future global settings that apply across all commands

### How Configuration Works

The configuration system operates through the following mechanisms:

1. **Automatic Loading**: When you run a command, the CLI checks for a file in your current directory `.supernova.json`
2. **Command Options**: Any options defined in the configuration file for the current command are automatically applied
3. **Override Precedence**: Command-line flags take precedence over configuration file values
4. **Automatic Saving**: After a successful command execution, the CLI saves the used options back to the configuration file

### Example Configuration

Here's an example of a configuration file for token synchronization:

```json
{
  "commands": {
    "figma-tokens-sync": {
      "mode": "single-file",
      "dryRun": false
    }
  },
  "global": {}
}
```

### Benefits

Using the configuration file offers several advantages:

- **Simplifies Command Usage**: No need to repeatedly type the same options
- **Improves Workflow Efficiency**: Saves time and reduces errors when executing commands
- **Enhances Team Collaboration**: Share consistent settings across your team by committing the configuration file to version control
- **Supports CI/CD Integration**: Makes it easier to integrate CLI commands into automated pipelines

### Command-Specific Configuration

Each command can store its specific configuration options. For example:

1. **Import Storybook Command**: Stores paths and IDs needed for importing

```json
   "import-storybook": {
     "dir": "./storybook-static",
     "designSystemId": "37355",
     "versionId": "37352"
   }
```

### Managing Configuration

The CLI handles configuration automatically:

- **Required Flags**: If a required flag has a value in the configuration file, it becomes optional in the command line
- **Updating Values**: When you provide a flag in the command line, its value is saved back to the configuration file for future use
- **Feedback**: The CLI will inform you when configuration is loaded and saved

### Best Practices

- **Version Control**: Consider adding the file to version control if you want to share settings with your team `.supernova.json`
- **Sensitive Information**: Avoid storing sensitive information in the configuration file as it might be committed to version control

### Troubleshooting

If you encounter issues with your configuration:

1. **Check File Format**: Ensure the JSON is valid and properly formatted
2. **Check Permissions**: Ensure the CLI has write permissions in the current directory
3. **Reset Configuration**: Simply delete the file to start fresh `.supernova.json`

By leveraging the configuration file, you can significantly streamline your workflow when working with the Supernova CLI.

## Next Steps

After successfully logging in, you can use other Supernova CLI commands.
See the additional use cases section for more information about available commands.

### Use cases

Following is the list of use cases for Supernova CLI. We will be adding more over time, stay tuned!

- [Host private storybook](./docs/storybook-hosting.md)
- [Synchronize Figma Token Plugin data](./docs/figma-tokens-sync.md)
- [List workspaces, design systems, brands and themes](./docs/list-workspaces.md)

## Contributions

If you have additional ideas about how to make this project better, let us know by opening an issue! You can also open pull requests if you've worked on improving something yourself and would like to contribute back to the community.

We will be reviewing feature-pull-requests on case-by-case basis, but in general, we are super open to your new ideas and we welcome them! And finally, thank you for your support! You are an amazing community.

Supernova Engineering Team