Frontastic CLI

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

If you're using Windows, please see this article for installation details.

Getting started

You'll have problems if you run Frontastic CLI in the same checkout as a container/VM. You need to do a clean Git checkout of your project. Also, Frontastic CLI requires that there's no container/VM with Frontastic running on your machine when using it.

To get Frontastic CLI running on your system, you'll need Homebrew for macOS or Linux.

With Homebrew you can just run brew tap frontasticgmbh/tap && brew install frontastic-cli to install the Frontastic CLI. 

Then you can run  brew upgrade frontastic-cli at any time to get updates to the Frontastic CLI.

You can also use Homebrew to install Yarn if you don't have Yarn already installed on your computer. Just run brew install yarn.

The below steps always require the latest version of Frontastic CLI. Please check you have the right version installed.

Basic usage

Run  frontastic init in the root directory of your code repository checkout
This will iterate you through some questions for generating the base Frontastic CLI configuration:
  • Enter the full path to the project root – you can just press enter if you're already in your project root
  • Select the project you want to work on – this will only appear if you have more than 1 project in your folder
  • Choose if you want to use a Frontastic Machine or a Staging Server – select Staging server if you're only working on just the frontend
  • Then enter the hostname of your staging server – this will usually be your project name then a dash (-) then your customer name followed by, for example, if our project name was awesome and our customer name was shop, we'd use

You can run frontastic init again at any time if you want to change your configuration.

Run yarn install in the root directory of your code repository checkout to get all JavaScript dependencies installed locally 
Start the local development service using frontastic run

That's it! You can now access your development environment under: http://<project>-<customer> (basically your staging URL with http:// and .local appended).

When you're done for the day, you can stop the development service by hitting <Ctrl>-<C>

Since you're not running a local backend server, any changes to the PHP code or configuration files like project.yml won't have an immediate effect. These changes need to be deployed to Staging first. Alternatively, you can use a Frontastic Machine.

File synchronization

If you need to work on the Backend-for-Frontend, also known as the PHP code, you can enable file synchronization to the remote server. Note that this only works with a Frontastic Machine.

To do this:

Run frontastic init and select backend file synchronization
Start Frontastic CLI as usual with  frontastic run to do frontend development locally and have backend-changes synced to the remote machine or use frontastic filesync to only start the sync to the remote machine
You can change this configuration any time by again running frontastic init.


macOS refuses to start Frontastic CLI

If you get a message saying that the application can't be started because the developer can't be verified, you have to allow the application in the General tab of the Security & Privacy settings in your System Preferences. See here for more info.

Yarn has errors on installation

Are you sure you did a fresh checkout after using a container/VM? If not, please do so. Or you can remove all node_modules folders (even those in paas/...) and try again. You can achieve to clean up your entire code base to the state of a fresh clone using git clean -f -d -x.

Frontastic CLI claims ports are in use

You might have a Frontastic container/VM running in another directory. Make sure this is shut down properly using vagrant halt in the directory in question. Another reason might be that you have a webserver running locally on port 80 please shut this down before starting the Frontastic CLI.

In rare cases, there might also be a dangling process of a utility used by Frontastic CLI. To check this see if there are processes running named mutagen or traefik. If so, terminate those and try again. If that does still not help, restarting your computer to release the ports from zombie processes might help.

Error: Project already running

If you see the error Project already running, this means that there's a .frontastic/mutagen.yml.lock file still running from an unclean stopped filesync process or from one currently running.

Check if a Mutagen process is running by using ps ax | grep mutagen and then kill the process. You can then remove the lock file and try the Frontastic CLI again.

‹ Back to article list

Next article ›

Frontastic CLI for Windows

Still need help? Contact us Contact us