CLI

The CLI is the central entry point for frontend development. It's possible to run webpack, which prepares all frontend code, directly on your local machine and everything else in the cloud.

Prerequisites

  • Homebrew installed locally for macOS or Linux
  • scoop installed locally for Windows
  • Node installed locally (version 14-16)
  • Yarn installed locally (version 1.22+) GitHub customer repository studio
  • Your favorite IDE
  1. Clone your company's GitHub customer repository to your local machine
  2. Open the terminal at the root of the project
  3. Run the command below to install the latest version of the CLI
brew tap frontasticgmbh/tap && brew install frontastic-cli
scoop bucket add FrontasticGmbH_scoop-bucket https://github.com/FrontasticGmbH/scoop-bucket
scoop install frontastic-cli

The CLI doesn't work with the Git Bash terminal in Windows. You can use another terminal such as cmd, Powershell, or the Windows Terminal.

  1. Run frontastic init to initialize your project
    You'll be asked some questions to set up your configuration. To get started quickly, you can use the answers below:
  • Which project do you want to work on? – this will only appear if you have more than 1 project in your folder
  • Are you using a sandbox or a staging server for development? - We're using a staging server in this example so we'll select Staging server\

You'd also need to generate an SSH key if you're using a sandbox for development.

  1. Run frontastic install, to install all the dependencies
  2. Run frontastic run, to run the project locally
    Once you see the dashboard (example below) and everything has been set up successfully, you're ready to start creating your commerce site.

005f5e8 Frontastic CLI dashboard new


Commands and hotkeys

Commands
Use the tabs below to see the different commands for the CLI:

  • frontastic init
    This command configures the project for you and will prompt you to use a staging server or set up the sandbox. You'd also need to generate an SSH key if you're using a sandbox for development.

It may ask you for your sudo password, this is needed as the CLI updates your /etc/hosts file and that needs superuser rights.

  • frontastic install
    This command runs the installation for all dependencies for your project.

  • frontastic run
    This command starts the Next.js frontend process by running yarn dev, the build process of the extensions and the file synchronization of the build artifacts to the sandbox so that they run there. It also sets up a hostname  <project>-<customer>.frontastic.io.local to access the studio of the sandbox.

  • frontastic pull
    Manually trigger replication of changes made in the studio to the sandbox. This is the same as opening an SSH connection to the sandbox and calling paas/replicator/bin/pull there.
    Debugging the pull command
    If you get errors running frontastic pull, check if the pull script on the sandbox works by directly executing it:

    1. Connect to the current sandbox through SSH (by running frontastic ssh).
    2. Execute cd /var/www/frontastic && /var/www/frontastic/paas/replicator/bin/pull.
      If the direct command runs fine, report it as a problem with the CLI.
      If you get the same error, then there's something wrong with your sandbox. The fastest solution is probably to create a new sandbox.
  • frontastic ssh
    Connect to the sandbox using SSH connection to access the filesystem and manually run the replicator.
    Debugging SSH issues
    When the CLI errors because of an SSH connection issue, the first thing to try should be connecting to the sandbox using SSH manually.
    On Linux and macOS, this is as easy as running:
    ssh vagrant@sandbox-name.frontastic.dev

    On Windows, the CLI doesn’t use just any SSH client currently installed on the system. Especially, it doesn’t use the OpenSSH client, which comes with Windows 10 and later by default. This is because mutagen also doesn’t use it, and testing with another client than mutagen would make the test useless.

    • C:\Program Files\Git\usr\bin
    • C:\Program Files (x86)\Git\usr\bin
    • C:\msys32\usr\bin
    • C:\msys64\usr\bin
    • C:\cygwin\bin
    • C:\cygwin64\bin

    So when testing the connection manually, make sure to use the SSH client binary in the first path from above which is present at the computer.

    This should prompt for the sandboxes SSH password (which can be found in the studio) and after entering that it should give a shell on the sandbox.

  • frontastic help
    Run the help command to open up the help menu.

Flags

  • frontastic --version
    The version flag outputs the version number of the CLI that you're using
  • frontastic [command] --verbose
    To see detailed logs and error messages from the command.
  • frontastic [command] --help
    Use the help flag on any command to get information on what that command does

Hotkeys
When you run frontastic run, you'll see our dashboard.

Here, you can see the current status of the processes it's running as you're using the CLI, so you can easily see when a process stops working or a connection is lost.

The error section will highlight the number of unread errors for Next.js, backend build, and sandbox. To see the error, you can use the hotkeys to go to the window where the error is occurring to find out more information. When you go back to the dashboard, the unread errors will be reset.

The startup checks section shows you the initial setup of the CLI processes.

When you're on the dashboard, you can use the below hotkeys:

  • d – dashboard
    This brings up the home of the CLI. You’ll see the status of every process at a glance.
  • n – Next.js logs
    This is where we show all the logs and error messages from the Next.js process.
  • b - backend build logs
    You’ll find the Webpack build log for extensions here.
  • f - filesync logs
    Shows the logs from the Mutagen file synchronization process.
  • s - sandbox logs
    You can see the logs from your sandbox instance on this screen.
  • p - filesync pause
    You can use this to pause the file synchronization temporarily.
  • t – opens your test URL in a browser
  • ctrl-c – Exits the CLI (if using Windows, you might need to type exit instead)

When you're in the logs, you can use the below hotkeys to navigate through the logs:
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 – moves to the top of the page
G or end – moves to the bottom of the page
ctrl-f or page down – moves down 1 page
ctrl-b or page up – moves up 1 page
ctrl-l – saves the current log window to the TXT file
ctrl-m - add a marker to the end of the log to make identifying new messages easier

In the sandbox log view (s), use the arrow keys (up and down) to move up or down in the logs. Only the logs preview is shown by default, press Enter to see additional details for the selected log message, and you'll see the detailed log and its context in a pop-up. Press Esc to close the log details.

You can filter messages by a search term (press / and type the term) or by regular expression (press r and type the regular expression, an invalid or incomplete expression will turn red). Messages from our internal API hub are filtered out by default. To change that, press a.

You can also filter the messages by log level by pressing (capital) F. This will show a window, where you can check the individual log levels to be displayed. Use the Tab key to navigate and Space to toggle the checkboxes. When finished, you can press Esc or navigate to the OK button and press Enter. To reset the selection (show all levels again), navigate to the Reset button and press Enter.

85e24e0 2022 06 20 14 25

Upgrading the CLI

We're always making improvements to the CLI. We recommend you run the upgrade command at least once a week. You can also visit our CLI changelog to see the latest updates.

To upgrade to the latest version of the CLI run the below command:

brew upgrade frontastic-cli
scoop update frontastic-cli