Leaf CLI ​

Leaf CLI creates and runs Leaf projects, installs modules, sets up frontend tooling, and shares compact project context with AI assistants. One tool, from leaf create to leaf deploy.

Installation ​

Make sure Composer is available on your machine:

composer --version

Install Leaf CLI globally:

composer global require leafs/cli -W

composer global require leafs/cli:^5.0 leafs/sprout:^5.0 -W

composer global remove leafs/sprout && composer global require leafs/cli:^5.0 -W

Verify the install by running:

leaf

composer global config bin-dir --absolute

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

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

Creating apps ​

Use leaf create to start a new project. You can choose the app shape interactively, or pass a flag when you already know what you want.

leaf create my-app

You can skip the prompt:

leaf create my-app --lite
leaf create my-app --mvc
leaf create my-app --api
leaf create my-app --console

Running your app ​

Move into your project directory and run the development server:

cd my-app
leaf serve

By default, Leaf serves your app on localhost:5500. If your project uses Vite, queue workers, or Redis, leaf serve starts those alongside the PHP server and streams their output into one terminal, with each line labeled by its source ([vite], [server], [queue]) so you always know where a message came from.

leaf serve --port=8080
leaf serve -p 8080

You can also serve a project from another directory:

leaf serve /path/to/your/app

Use --port when you need the server on a specific port:

leaf serve --port=8080

Sharing AI context BetaBetaPortable project context is new in Leaf 5The leaf context command scans real projects of every shape, so its output format and detection rules may still change while it settles.Introduced in Leaf 5 ​

Agents running inside your project use .leaf/CONTEXT.md as shared project memory. They read it alongside the filesystem and sync useful changes back when they finish, so the next agent starts with the latest map. Leaf MVC and projects created through Leaf CLI need no extra AI configuration.

Use leaf context only when an external assistant cannot access the project:

leaf context

This scans your project and prints a compact handoff: your actual routes with their handlers and middleware, installed modules, models, schema files, and environment key names (names only, never values), with the shared context appended at the end. Paste that output into the external assistant before asking for larger changes. The output is a portable snapshot, not a replacement for the two-way .leaf/CONTEXT.md used inside the project. The two are opposite halves: the file holds goals and decisions, the command generates the mechanical map.

Scaling a project BetaBetaThe app upgrade workflow is still evolvingThe leaf up command can organize a small Leaf app into MVC structure, but its migration rules and generated output may change while the workflow is tested across more real projects.Command version: 0.1 ​

Not all apps require a full structure from the start. With Leaf, you can start as small as a single index.php file hosting your application. This is great for prototypes, scripts, and small tools, but as your app grows, you may want to organize it into a more structured MVC format.

We added the leaf up command to help you scale your app without switching frameworks or rewriting everything by hand. It can move assets, organize controller-like code, and prepare MVC conventions around the app you already started.

leaf up

The first time you run leaf up, it will generate a .leaf/migration.yml file that describes the changes it will make to your project. You can edit this file to point to different directories or change the structure before running the migration. Once you're ready, run leaf up again to apply the changes.

Running commands ​

Use leaf run to execute scripts from your app's composer.json.

leaf run my-command

This keeps project-specific commands close to the app while still giving you one consistent CLI entry point.

The global leaf command is also the only entry point you need inside a project: it automatically forwards project commands like g:controller, g:model, and db:migrate into your app's console, so leaf g:model flight and php leaf g:model flight do the same thing. php leaf only knows your project's commands, while the global leaf command handles both those and everything the CLI itself provides, so you can simply use leaf everywhere.

Dependency management ​

Leaf CLI adds a friendlier layer on top of Composer for Leaf modules and regular Composer packages.

Installing packages ​

Install a Leaf module:

leaf install auth

You can also include the full Composer package name:

leaf install leafs/auth

Install multiple packages at once:

leaf install auth db mail
leaf install auth db illuminate/support

Install a specific version with @:

leaf install [email protected] illuminate/[email protected]

Uninstalling packages ​

Use uninstall to remove packages:

leaf uninstall auth
leaf uninstall auth db illuminate/support

View commands ​

Leaf CLI also includes commands for frontend and view tooling.

leaf view:install
leaf view:build

Use view:install to set up a view engine or frontend integration, and view:build to build frontend assets for production.

view:install takes one flag per integration:

leaf view:install --blade      # blade templating
leaf view:install --react     # react via inertia
leaf view:install --vue       # vue via inertia
leaf view:install --svelte    # svelte via inertia
leaf view:install --tailwind  # tailwind css
leaf view:install --vite      # vite asset bundling

In an MVC app, these wire into the app's structure (app/views, vite config, the works). They work in lite apps too: as of Leaf CLI 5.0.6, view:install writes your views to a views/ folder in the project root and configures your app's view paths automatically. You can read more about how this fits together in the Vite docs. And if your single file is outgrowing itself, leaf up can take you to full MVC structure whenever you're ready.

Command reference ​