CLI

Install the 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.

Commands, flags, and hotkeys

You interact with the CLI using commands and hotkeys. The 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.

• frontastic upload uploads 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.
• 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.

• 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.

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:

  Update frontastic-cli on macOS/LinuxTerminal

  brew update && brew upgrade frontastic-cli

• On Windows:

  Update frontastic-cli on WindowsTerminal

  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.

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.

   Test run the clean up commandTerminal

   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.

   Print the files that will be removedTerminal

   git clean -fdx -e .idea

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

   Remove untracked filesTerminal

   frontastic init

Chromium not working on M1 Mac

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

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:

   Install ChromiumTerminal

   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. 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.

   Activate Anywhere option in security settingsTerminal

   sudo spctl --master-disable

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

   Run Chromium with xattr -cr commandTerminal

   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.

   Update Chromium configuration in .zshrcTerminal

   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.

   Remove node_modulesTerminal

   rm -rf node_modules/
   Remove package-lock.jsonTerminal

   rm -rf package-lock.json
   Remove cacheTerminal

   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.

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.

   Check the processor architectureTerminal

   node -p process.arch
   • If this command outputs arm64, go to step 2.
   • If not, contact the Frontend support team.

2. Run the following command to install Rosetta.

   Install RosettaTerminal

   softwareupdate --install-rosetta

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

   Change zsh binary typeTerminal

   arch -x86_64 zsh

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

   Install Node.js 16 LTSTerminal

   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.

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, you might face issues installing the CLI. In such case, you can use the CLI without installation by following these steps:

1. From the release page 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.