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 installed locally for macOS or Linux
  • scoop installed locally for Windows
  • Node.js installed locally (version 16.x)
  • 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:

    Install frontastic-cli on macOS and LinuxTerminal
    brew tap frontasticgmbh/tap && brew install frontastic-cli
  • For Windows, run the following commands:

    Add scoop bucket on WindowsTerminal
    scoop bucket add FrontasticGmbH_scoop-bucket https://github.com/FrontasticGmbH/scoop-bucket
    Install frontastic-cli on WindowsTerminal
    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 --multitenant 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 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

  • d opens the CLI dashboard.
  • n displays the logs and error messages from the Next.js process.
  • b displays the webpack build log for extensions.
  • i displays internal logs.
  • t opens your test URL in a browser.
  • S (both shift-s and Caps Lock-s) opens the URL to the studio in a browser.
  • ctrl-c exits the CLI. On Windows, you might need to type exit instead.

Logs

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

  • h or left arrow move left.
  • l or right arrow move right.
  • j or down arrow move down.
  • k or up arrow move up.
  • g or home move to the top of the page.
  • G or end move to the bottom of the page.
  • ctrl-f or page down move down one page.
  • ctrl-b or page up move up one page.
  • ctrl-l saves the current log window as a .txt file.
  • ctrl-m adds a marker to the end of the log to make it easier to identify new 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/Linuxshell
    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 --multitenant

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 running frontastic install on an M1 Mac.

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.

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