# CLI

Use the CLI to set up, develop, and manage your website.

The CLI is the central entry point for frontend development. Its primary function is to transpile and bundle your code for development.

**Prerequisites**

- [Homebrew](https://brew.sh/) installed locally for macOS or Linux
- [scoop](https://scoop.sh/) installed locally for Windows
- Node.js installed locally (version 22.x; other versions greater than or equal to 18 are also supported, but not recommended)
- Yarn installed locally (version 1.22+)
- Your favorite IDE
- Access to your GitHub customer repository
- Access to your Studio (`https://<customer>.frontastic.io`)

## Install the CLI

To install the latest version of the CLI, open a command-line tool and run one of the following commands based on your operating system.

- For macOS and Linux, run the following command:

  ```console title="Install frontastic-cli on macOS and Linux"
  brew tap frontasticgmbh/tap && brew install frontastic-cli
  ```

- For Windows, run the following commands:

  ```console title="Add scoop bucket on Windows"
  scoop bucket add FrontasticGmbH_scoop-bucket https://github.com/FrontasticGmbH/scoop-bucket
  ```

  ```console title="Install frontastic-cli on Windows"
  scoop install frontastic-cli
  ```

## CLI dashboard

The CLI dashboard consists of the following panes:

- **Status** displays the status of the running processes. For example, you can see if a process stops or a connection is lost.

- **Errors** displays the number of unread errors for Next.js and backend extensions build. To read error logs, use the related hotkeys to open the window where the error occurred. When you return to the dashboard, the unread errors will be reset.

- **Startup checks** displays the status of the CLI startup checks.

- **Test URL** displays the URL for the test environment.

- **Studio URL** displays the URL for the Studio.

- The last pane displays the available [hotkeys](/frontend-development/cli.md#hotkeys).

![The six sections of the CLI dashboard: Status, Errors, Startup checks, Test URL, Studio URL, and hotkeys.](https://docs.commercetools.com/frontend-development/images/cli-dashboard.png)

## Commands, flags, and hotkeys

You interact with the CLI using [commands](/frontend-development/cli.md#commands) and [hotkeys](/frontend-development/cli.md#hotkeys). The [flags](/frontend-development/cli.md#flags) let you provide additional options to the commands.

### Commands

- `frontastic init` configures the project and prompts you to enter the Studio user API token.

  To copy your API token, follow these steps:

  1. From the Studio home page, click the **Account** icon and select **Profile**: the **User settings** dialog opens.
  2. Copy the value in the **API token** field.

  You might need to provide your `sudo` password as the CLI updates your `/etc/hosts` file, which needs superuser rights.

- `frontastic install` runs the installation for all dependencies for your project.

- `frontastic run` executes the following actions:

  - Starts the Next.js frontend process by running `yarn dev`.
  - Starts the build process of the extensions.

- `frontastic scaffold` creates a commercetools Frontend project when [setting up a Git repository](/frontend-development/set-up-custom-repository.md#set-up-a-new-project).

- `frontastic upload` [uploads](/frontend-development/set-up-custom-repository.md#deploy-backend-extensions) the specified backend build to the Studio.

- `frontastic help` runs the `help` command to open up the help menu.

### Flags

- `frontastic --version` displays the version of your CLI.
- `frontastic [command] --verbose` displays logs and error messages from the specified command.
- `frontastic [command] --help` displays information about the specified command.

### Hotkeys

#### Dashboard

- `b` displays the webpack build log for extensions.
- `d` opens the [CLI dashboard](/frontend-development/cli.md#cli-dashboard).
- `i` displays internal logs.
- `n` displays the logs and error messages from the Next.js process.
- `S` (either `Shift+s` or `Caps Lock+s`) opens the URL to the Studio in a browser.
- `t` opens your test URL in a browser.
- `Control+c` exits the CLI. On Windows, you might need to type `exit` instead.

#### Logs

In the log windows, you can use the following hotkeys.

The hotkeys for extension logs differ from the hotkeys for other log windows. For further information, see [Extension logs](/frontend-development/cli.md#extension-logs).

- `g` or `home` move to the top of the page.
- `G` (either `Shift+g` or `Caps Lock+g`) or `end` move to the bottom of the page.
- `h` or `left arrow` move left.
- `j` or `down arrow` move down.
- `k` or `up arrow` move up.
- `l` or `right arrow` move right.
- `Control+f` or `page down` move down one page.
- `Control+b` or `page up` move up one page.
- `Control+l` saves the current log window as a `.txt` file.
- `Control+m` adds a marker to the end of the log to help identify new log messages.

#### Extension logs

In the extension logs window, you can use the following hotkeys:

- `c` copies the selected log message to the clipboard.
- `F` (either `Shift+f` or `Caps Lock+f`) opens a filter dialog where you can filter messages by log level and other criteria.
- `j` or `down arrow` move down.
- `k` or `up arrow` move up.
- `r` initiates a search with regular expressions. Enter the expression to filter log messages.
- `/` initiates a search. Enter the search term to filter log messages.
- `Enter` displays the detailed view of the selected log message.
- `Control+h` adds a marker at the end of the log to help identify new log messages.

You can open a help window listing the hotkeys by pressing `h`.

## Update the CLI

We recommend keeping the CLI up-to-date to get the latest features and bug fixes. To update the CLI, run one of the following commands.

- On macOS or Linux:

  ```console title="Update frontastic-cli on macOS/Linux"
  brew update && brew upgrade frontastic-cli
  ```

- On Windows:

  ```console title="Update frontastic-cli on Windows"
  scoop update frontastic-cli
  ```

## Troubleshoot

Following are the most common issues with the CLI and their resolution.

### CLI not starting on macOS

If you get a message saying the application cannot be started because the developer cannot be identified, you must [allow the application from **System Settings** on your computer](https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac).

### ENOENT or Yarn install errors

If you experience a problem with `node_modules` or an error in the CLI containing `ENOENT`, you must reset your local setup. To do so, follow these steps:

1. Run the following command to print the files that will be removed.

   ```console title="Test run the clean up command"
   git clean -fdxn -e .idea
   ```

2. Make sure that the files can be removed. Then, run the following command to remove the files. This will delete the files that aren't tracked by Git and reset your local setup.

   ```console title="Print the files that will be removed"
   git clean -fdx -e .idea
   ```

3. Run the following command to re-initialize your project.

   ```console title="Remove untracked files"
   frontastic init
   ```

### Chromium not working on M1 Mac

You could get the following error when running `frontastic install` on an M1 Mac.

```shell title="Chromium not working error"
The chromium binary is not available for arm64:
If you are on Ubuntu, you can install with:

 apt-get install chromium-browser

path-to-project/node_modules/puppeteer/lib/cjs/puppeteer/node/BrowserFetcher.js:112
 throw new Error();
```

To fix the error, follow these steps:

1. Install Chromium on your local machine by running the following command:

   ```console title="Install Chromium"
   brew install chromium
   ```

   - If Chromium runs correctly, go to step 5.
   - If you get a message saying the application cannot be started because the developer cannot be identified, go to step 2.

2. [Allow Chromium from **System Settings** on your computer](https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac). When doing so, you must select **Anywhere**.

   - If **Anywhere** is available, select it. Then, launch Chromium.

     - If Chromium runs correctly, go to step 5.
     - If you get the `Chromium is damaged and can't be opened` message, go to step 4.

   - If **Anywhere** is not available, go to step 3.

3. Run the following command to activate the **Anywhere** option. Then, repeat step 2.

   ```console title="Activate Anywhere option in security settings"
   sudo spctl --master-disable
   ```

4. Run the following command, Chromium should now run correctly. Then, go to step 5.

   ```console title="Run Chromium with xattr -cr command"
   xattr -cr /Applications/Chromium.app
   ```

5. Edit the `.zshrc` file on your computer by adding the following code. It allows skipping future installations of Chromium.

   ```console title="Update Chromium configuration in .zshrc"
   export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
   export PUPPETEER_EXECUTABLE_PATH=`which chromium`
   ```

6. Run the following commands to remove the existing `node modules`, `package-lock.json`, and `cache` from the project.

   ```console title="Remove node_modules"
   rm -rf node_modules/
   ```

   ```console title="Remove package-lock.json"
   rm -rf package-lock.json
   ```

   ```console title="Remove cache"
   rm -rf .cache
   ```

7. Close your command-line tool and reopen it. Then, run `frontastic install` to install all dependencies.

### Node-darwin-arm64 error on M1 Mac

You could get the following error when using Node.js version 16 and running `frontastic install` on an M1 Mac.

```text title="M1 Mac error message"
Error: Cannot find module 'node-darwin-arm64/package.json
```

To fix the error, follow these steps:

1. Run the following command to check if the Apple Silicon M1 chip is causing the error.

   ```console title="Check the processor architecture"
   node -p process.arch
   ```

   - If this command outputs `arm64`, go to step 2.
   - If not, contact the [commercetools support team](https://support.commercetools.com/).

2. Run the following command to install Rosetta.

   ```console title="Install Rosetta"
   softwareupdate --install-rosetta
   ```

3. Run the following command to use the `x86 64-bit` binary of zsh.

   ```console title="Change zsh binary type"
   arch -x86_64 zsh
   ```

4. Run the following command to install the Node.js 16 long-term support version (LTS).

   ```console title="Install Node.js 16 LTS"
   nvm install lts/gallium
   ```

5. Run `frontastic install`.

### CLI marked as virus on Windows

Windows could mark the CLI as a virus and you might get a threat quarantined message. On close, Windows might delete the `.exe` file, and you will get a message like the following.

```text title="Virus error message on Windows"
Error:
Couldn't update hosts: fork/exec C:\Users\track\Desktop\frontastic-cli\frontastic.exe: Operation did not complete successfully because the file contains a virus or potentially unwanted software
```

To fix the error, you must edit Windows settings as follows:

1. On your computer, go to **Windows Security** > **Virus & Threat Protection** > **Protection History**.

2. Search for the quarantined CLI `.exe` file and select it.

   Ensure it's the CLI `.exe` file and not a real threat with a similar filename.

3. Click **Actions** and select **Restore**.

### Cannot install the CLI when using Docker

When creating a Docker image for your [custom CI](/frontend-development/set-up-custom-repository.md#deploy-backend-extensions), you might face issues [installing the CLI](/frontend-development/cli.md#install-the-cli). In such case, you can use the CLI without installation by following these steps:

1. From the [release page](https://github.com/FrontasticGmbH/frontastic-cli/releases) of the CLI repository, download the archive for your operating system and architecture.
2. Extract the archive and bundle the `frontastic` binary file into the Docker image.

When using the CLI without installation, you can only run the `upload` command.

## Related pages

- [Area overview page with navigation](/frontend-development.md)
- [Previous page: Main development concepts](/frontend-development/development-concepts.md)
- [Next page: Manage project configuration](/frontend-development/api-hub-configuration.md)
- [Search documentation and API specs](/search.md)