Leaf CLI

Command center

Create, run, extend, and explain your Leaf app from one CLI.

Leaf CLI is the fastest way to start an AI-ready Leaf project, run it locally, install first-party modules, scaffold frontend tooling, and share compact context with external assistants.

terminal

$ composer global require leafs/cli -W

$ leaf create my-app

$ cd my-app

$ leaf serve

What it handles

Project shape

Start with lite or MVC without changing ecosystems later.

Modules

Install auth, db, mail, queues, billing, and other Leaf packages quickly.

AI workflow

Start AI-ready, with portable context export when an assistant cannot access the project.

Installation

Make sure Composer is available on your machine:

composer --version

Install Leaf CLI globally:

composer global require leafs/cli -W

Getting a conflict about leafs/sprout?

If your global composer.json directly requires an older leafs/sprout, composer refuses the update — -W can bump dependencies, but it never overrides a version you pinned yourself. Update both constraints together:

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

Or, if you never use sprout on its own, drop the pin and let Leaf CLI manage it:

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

Verify the install by running:

leaf

01 / AvailabilityGlobal commandThe leaf command becomes available anywhere on your machine.

02 / EcosystemComposer-poweredLeaf CLI uses Composer underneath, so it fits naturally into PHP workflows.

[Error] command not found: leaf

If you get an error saying leaf: command not found, add Composer's global bin directory to your system's PATH. You can find the directory with:

composer global config bin-dir --absolute

Common locations:

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

On Bash:

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

On Zsh:

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

Entry pointFlagBest for

Basic app--litePrototypes, scripts, small tools, single-file starts.

MVC app--mvcFull-stack products, teams, views, controllers, and structure.

API app--apiBackends, mobile apps, headless products, and frontend clients.

Console app--consoleCLI tools built with Seedling.

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.

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

Automatic dependency installation

When running your app, Leaf will automatically try to install missing dependencies if no vendor directory is found in the project.

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.

leaf context is in beta

The scan covers the common project shapes, but real projects always find new ones. If leaf context misses your routes or trips on your setup, open an issue and we'll patch it quickly.

Prompt with context

Add billing, protect the dashboard, and create the webhook route.

AI sees

routes

modules

entry point

structure

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.

leaf up is in beta

The migration rules are still being tested against more real projects. Review the generated .leaf/migration.yml before applying, commit your work first, and if leaf up gets your project wrong, open an issue so we can fix it for everyone.

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.

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 auth@4.0 illuminate/support@9.0.2

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

These wire into an MVC app's structure (app/views, vite config, the works). In a lite app, run leaf up first — moving to views is usually the moment a single file wants real structure anyway.

Command reference

CommandUse

leaf createCreate a new Leaf project.

leaf serveRun a local development server.

leaf contextPrint compact context for an external assistant.

leaf upScale a basic app into MVC structure.

leaf installInstall Leaf modules or Composer packages.

leaf uninstallRemove modules or packages.

leaf runRun a script from composer.json.

leaf view:buildBuild frontend assets.