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...
Installation
Video Docs
You can take a look at our leaf cli setup walkthrough on youtube.
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
NOTE
To get leaf cli installed permanently, you will need to add your composer bin your .bashrc
or .zshrc
file on mac and linux.
zsh:
echo 'export PATH="$PATH:$HOME/.composer/vendor/bin"' >> ~/.zshrc
source ~/.zshrc
bash:
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.
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
>
TIP
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
.
Versioning
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.
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
Versioning
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
| |__/ -_) _` | _| | (__| |__ | |
|____\___\__,_|_| \___|____|___|
Usage:
command [options] [arguments]
Options:
-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
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.