CLI

Install and run the CLI

1. Clone your GitHub customer repository to your local machine.

2. Open the terminal at the root of the project.

3. To install the latest version of the CLI, run the following command.

   • For macOS or Linux:

     brew tap frontasticgmbh/tap && brew install frontastic-cli

   • For Windows:

     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.

4. To initialize your project, run frontastic init and answer the following questions to set up your configuration:

   • Which project do you want to work on?. This question will only appear if you have more than one project in your folder.

   • Are you using a sandbox or a staging server for development?

     If you're using a sandbox, you must generate an SSH key.

5. To install all the dependencies, run frontastic install.

6. To run the project locally, run frontastic run. Upon completion, the CLI dashboard is displayed.

CLI dashboard

The CLI dashboard has six sections:

• 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, backend build, and the sandbox. 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

Commands

• frontastic init configures the project and prompts you to use a staging server or to set up the sandbox.

  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.
  • Starts the file synchronization of the build artifacts to the sandbox so that they run there.
  • Sets a hostname <project>-<customer>.frontastic.io.local to access the studio of the sandbox.

• frontastic pull triggers the 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.

  If you get an error when 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 this command runs correctly, it is a CLI problem.
     • If you get the same error, it is a sandbox problem. The fastest solution is to create a new sandbox.

• frontastic ssh executes the connection to the sandbox using SSH connection to access the filesystem and manually run the replicator.

  If you get an error because of an SSH connection issue, test the SSH connection to the sandbox manually:

  • On macOS and Linux, run ssh vagrant@sandbox-name.frontastic.dev.
  • On Windows, follow these steps:
    1. Use the SSH client binary found at one of the following paths on your computer:
    • 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
    2. Enter the SSH password for sandboxes, which can be found in the studio: the sandbox can be accessed through a shell.

• 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.
• f displays the logs from the Mutagen file synchronization process.
• s displays the logs from the sandbox instance.
• i displays internal logs.
• p pauses the file synchronization temporarily.
• 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. In the Sandbox Log window, use the down arrow to move down in the list of log messages.
• k or up arrow move up. In the Sandbox Log window, use the up arrow to move up in the list of log messages.
• 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 to make it easier to identify new messages.

Sandbox Log

In addition to the hotkeys listed above, you can use the following in the Sandbox Log window:

• down arrow moves down in the list of log messages previews.
• up arrow moves up in the list of log messages previews.
• Enter displays the details of the selected log message.
• Esc closes the details of the selected log message.
• / [term] filters log messages by term. Messages from the API hub are excluded by default.
• r [regular expression] filters log messages by regular expression. An invalid or incomplete expression is displayed in red. Messages from the API hub are excluded by default.
• a displays log messages from the API hub.
• F (both shift-f and Caps Lock-f) opens the Filter window, where you can filter log messages by their severity level:
  • Tab selects the level toggles and the buttons.
  • Space activates/deactivates the level toggles.
  • Esc closes the Filter window. To close the window, you can also use Tab to select OK, then press Enter.

Update the CLI

To update the CLI, run the following command:

• On macOS or Linux:

  brew upgrade frontastic-cli

• On Windows:

  scoop update frontastic-cli