Announcing Forge CLI

Published on

Announcing Forge CLI

Today I'm happy to tag version 1.0 of Forge CLI - our latest open source package.

Now you might wonder: Forge CLI? Isn't that one of the many, many available Laravel Forge CLI tools? Why do we need another one?

So, yeah - Forge CLI is a CLI tool to interact with your Laravel Forge provisioned server and site. But it works different compared with all the other available tools out there. Let me show you what I mean.


You can install Forge CLI by requiring it as a global composer dependency:

composer global require beyondcode/forge-cli

After installing Forge CLI, you can link your local Laravel/PHP projects with existing sites on Laravel Forge:

After linking your site with Laravel Forge, the CLI tool will create a file called forge.yml for you. And this is the cool part about Forge CLI.

This YML file contains the site/server configuration that you have on Forge. It gives you the current deployment script, configured daemons, or configured webhooks.

And this makes it great to store this file in your git repository and have a representation of when a part of your Forge configuration was changed.

Forge CLI now knows that the current folder on your system is linked to a specific site and server on Laravel Forge - so all API requests are immediately targeting the correct server and site.


For example, lets say that you want to manually trigger a deployment on your linked Forge site. All you need to do is open the folder in your terminal and run:

forge deploy

Forge CLI will trigger the deployment, and show you the log output for that specific deployment.

Multiple environments

Forge CLI also has a concept of multiple environments. So you can link a site/server from Forge to a specific environment in your local directory.

This allows you to keep a single YML file that contains the configuration of both your staging and your production server. All Forge CLI commands allow you to pass the environment, in order to run this command on the given server.

For example, if we want to run a deployment on our staging environment, you could run this command:

forge deploy staging

Environment files

But Forge CLI allows you to do more than only triggering manual deployments. One common task is updating environment keys on your servers. This requires you to either SSH on your server, or manually edit the .env file via the Forge web-interface.

With Forge CLI, you can simply pull down the current environment file from Forge, edit it in your favorite code editor, and push the changes back to Forge.

forge env:pull staging

# This will write the environment to .env.forge.staging
# After making changes, you can push the file up to Forge

forge env:push staging

Modifying the server/site configuration

As I said, after linking your project with a Forge site, you have the forge.yml file. Now this file would only be half as useful, if it would only work one-way. But Forge CLI also allows you to synchronize the changes that you make to this file, back to Forge.

For example, you could modify the deployment script for your production environment:

  id: 1
  name: my-site
  server: 1
  quick-deploy: false
    - 'cd /home/forge/my-site'
    - 'git pull origin master'
    - '$FORGE_COMPOSER install --no-interaction --prefer-dist --optimize-autoloader'
    - ''
    - '( flock -w 10 9 || exit 1'
    - '    echo ''Restarting FPM...''; sudo -S service $FORGE_PHP_FPM reload ) 9>/tmp/fpmlock'
    - ''
    - 'if [ -f artisan ]; then'
    - '    $FORGE_PHP artisan migrate --force'
    - fi

After modifying the script, you can run forge config:push to synchronize the files changes with Laravel Forge.

And much more...

But there is a lot more that you can do with Forge CLI:

  • Restart system services
  • Restart your server
  • Create new Daemons and Webhooks
  • Push and pull nginx configuration
  • Read log files from your server

and much more...

So be sure to checkout the official documentation of Forge CLI.