Skip to content

Leaf CLI

Leaf CLI is a simple command line tool for creating and interacting with your leaf projects. You can do stuff like installing packages, interacting with your app, previewing your app...


Video Docs

You can take a look at our leaf cli setup walkthrough on youtube.

Watch the leaf CLI installation walkthrough

You can get this tool up and running on your system using composer:

composer global require leafs/cli

Make sure to place Composer's system-wide vendor bin directory in your $PATH so the leaf executable can be located by your system. This directory exists in different locations based on your operating system; however, some common locations include:

  • Windows: %USERPROFILE%\AppData\Roaming\Composer\vendor\bin
  • macOS: $HOME/.composer/vendor/bin
  • GNU / Linux Distributions: $HOME/.config/composer/vendor/bin or $HOME/.composer/vendor/bin

You could also find the composer's global installation path by running composer global about and looking up from the first line.

Eg (Adding composer bin to path linux):

export PATH=$PATH:$HOME/.config/composer/vendor/bin

Eg (Adding composer bin to path mac):

export PATH=$PATH:$HOME/.composer/vendor/bin
echo $PATH


To get leaf cli installed permanently, you will need to add your composer bin your .bashrc or .zshrc file on mac and linux.


echo 'export PATH="$PATH:$HOME/.composer/vendor/bin"' >> ~/.zshrc
source ~/.zshrc


echo 'export PATH="$PATH:$HOME/.composer/vendor/bin"' >> ~/.bashrc
source ~/.bashrc

Creating a leaf app

Video Docs

You can take a look at our leaf cli setup walkthrough on youtube.

Watch the leaf 3 installation walkthrough

To start a new project, simply open up your console or terminal and move into the directory you want to generate your project. From there, you can use the create command:

leaf create <project-name>

with leaf 3:

leaf create <project-name> --v3

or with leaf 2:

leaf create <project-name> --v2

This will now prompt you to select a preset

Creating a new Leaf app "<project-name>" in ./projects-directory.

* Please pick a preset 
  [0] leaf
  [1] leaf mvc
  [2] leaf api
  [3] skeleton


Note that you are to select a number, not type the name of the preset.

Selecting a number will generate a leaf app based on the associated preset. As you can see, there are 4 presets:

  • Leaf: a bare leaf project
  • Leaf MVC: a leaf MVC project with leaf 2
  • Leaf API: a leaf API project with leaf 2
  • Skeleton: a leaf skeleton project

After picking a preset, if no version was specified, leaf will display an interactive version picker like the one above:

* Select a version to use 
  [0] v3
  [1] v2

your project will be automatically generated and initialized. All you need to do is open it up and start coding 🚀

Adding Tests

From Leaf CLI v2.3, you will be asked if you want to add tests to your project. You can add tests by replying y.

* Add testing with Leaf Alchemy? [y, n] y

 - Adding alchemy for tests

For a quicker method, you can use the --phpunit or --pest option to add tests to your project using PHPUnit or Pest respectively. You can also use the --no-tests option to completely skip adding tests.

leaf create <project-name> --no-tests

Quick presets

Leaf CLI also provides a quicker way to initialize your project without having to go through the interactive installer. You can use the --mvc, --api, --basic and --skeleton options to generate your project based on a specific presets. --basic generates a raw leaf project.

eg: leaf create backend-api --api

This will create a leaf api project named backend-api.


If no version is specified, leaf displays the interactive installer to you, however, to quickly install a particular version, you can use the --v2 or --v3 options. These can be coupled with presets as well.

Leaf API 3 example:

leaf create backend-api --api --v3

Running your leaf apps

After generating your leaf app, you can cd into the directory and spin up a local dev server using leaf cli's serve command.

cd backend-api
leaf serve

You can also specify the port to run your leaf app on using the --port or -p options.

leaf serve -p 3000

File watching

In v2.1, you can also start the leaf server with hot module watching. This reloads your application anytime a change is made to your application code. To get started, simply start the leaf server with the --watch flag.

leaf serve --port 8000 --watch

Dependency Management

The serve command also now installs dependencies when there is no vendor folder present in the current working directory.

Video Docs

Working with packages and the leaf cli

Working with packages on the Leaf CLI

Testing your Leaf apps

Testing helps prevent bugs in your app which you may not catch until you publish your app to production. Leaf introduced a test runner which helps you initialize testing and run tests in your app without needing any config first. Alchemy has also been integrated into the Leaf CLI and so you can use it's functionality directly.

Setting up tests

Leaf CLI allows you to setup tests in your project with one command:

leaf test:setup

This command will generate Pest PHP tests for your application. If you however want to use PHPUnit, you'll need to pass the --phpunit option to the command.

leaf test:setup --phpunit

Running tests

To run tests you've setup or created, you can simply run the test command.

leaf test

Installing packages

This cli tool also adds a feature to install leaf packages from composer.

leaf install leafs/ui

If you are installing a leaf module or package, you can leave out the leafs/ part.

leaf install ui

You can also pass in a bunch of packages to install at once.

leaf install ui db illuminate/support


Leaf CLI also allows you to install a particular version of any package using @

leaf install ui@1.0 illuminate/support@9.0.2

Package Chaining

You can now add a bunch of packages to install as done with composer, npm and other CLIs as well.

leaf install db illuminate/support

Using this method, you can even add specific versions of some packages like this:

leaf install db illuminate/support@9.0.2 nesbot/carbon

Interactive Shell

You can also use the interactive shell to interact with your app.

$ leaf interact
>>> $user = new User;
>>> $user->name = "Mychi";
>>> $user->save();

Updating leaf cli

v2 contains an easy way to quickly update leaf cli to the latest version.

leaf update

Running Scripts

Leaf CLI also now allows you run scripts defined in your composer.json file. For example, if you have this in your composer.json:

You can run the test script like this:

leaf run test

Usage Guide

 _              __    ___ _    ___ 
| |   ___ __ _ / _|  / __| |  |_ v2.7.0
| |__/ -_) _` |  _| | (__| |__ | | 
|____\___\__,_|_|    \___|____|___|                       

  command [options] [arguments]

  -h, --help            Display help for the given command. When no command is given display help for the list command
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  completion  Dump the shell completion script
  create      [init] Create a new Leaf PHP project
  deploy      [publish] Deploy your leaf project
  help        Display help for a command
  install     Add a new package to your leaf app
  interact    Interact with your application
  list        List commands
  run         Run a script in your composer.json
  serve       Run your Leaf app
  test        Test your leaf application through leaf alchemy
  uninstall   Uninstall a  package
  update      Update leaf cli to the latest version
  test:setup  Add tests to your application

This is the full list of commands available with Leaf CLI 2. A new update command has been added to allow you seamlessly update leaf CLI without having to run a bunch of commands. You don't even need to run this manually since leaf cli will automatically check for updates and upgrade to the latest stable release.

Leaf CLI has loaded