Documentation

CLI

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

Copy for LLM
View as Markdown

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

Prerequisites

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:

    Install frontastic-cli on macOS and Linuxshell
    brew tap frontasticgmbh/tap && brew install frontastic-cli

  • For Windows, run the following commands:

    Add scoop bucket on Windowsshell
    scoop bucket add FrontasticGmbH_scoop-bucket https://github.com/FrontasticGmbH/scoop-bucket
    Install frontastic-cli on Windowsshell
    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.
The six sections of the CLI dashboard: Status, Errors, Startup checks, Test URL, Studio URL, and 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.

The hotkeys for extension logs differ from the hotkeys for other log windows. For further information, see 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:

    Update frontastic-cli on macOS/Linuxshell
    brew update && brew upgrade frontastic-cli

  • On Windows:

    Update frontastic-cli on Windowsshell
    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 commandshell
    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 removedshell
    git clean -fdx -e .idea

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

    Remove untracked filesshell
    frontastic init

Chromium not working on M1 Mac

You could get the following error when running frontastic install on an M1 Mac.
Chromium not working errorshell
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 Chromiumshell
    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 settingsshell
    sudo spctl --master-disable

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

    Run Chromium with xattr -cr commandshell
    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 .zshrcshell
    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_modulesshell
    rm -rf node_modules/
    Remove package-lock.jsonshell
    rm -rf package-lock.json
    Remove cacheshell
    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.
M1 Mac error messagetext
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 architectureshell
    node -p process.arch

  2. Run the following command to install Rosetta.

    Install Rosettashell
    softwareupdate --install-rosetta
  3. Run the following command to use the x86 64-bit binary of zsh.
    Change zsh binary typeshell
    arch -x86_64 zsh

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

    Install Node.js 16 LTSshell
    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.
Virus error message on Windowstext
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.
When using the CLI without installation, you can only run the upload command.