#Filament Plugin CLI

Scaffold new open-source Filament plugins with multi-branch git already configured, built with Laravel Zero. Fully non-interactive — every input is an argument or a flag, so it's meant to be driven by an AI agent (e.g. Claude Code's filament-plugin-creator skill) as much as by a human.

#What it does

filament-plugin create vendor/package "Description" generates the mechanical, repeatable part of a new Spatie-style Filament plugin, on the version branch(es) it belongs on — never main:

• Directory skeleton, boilerplate files (.editorconfig, .gitattributes, .gitignore, LICENSE.md, CHANGELOG.md, README.md, phpstan.neon.dist, phpunit.xml.dist)
• composer.json correct per branch (filament/filament, PHP floor, orchestra/testbench range — see the branch table below)
• Service Provider (PackageServiceProvider) and Filament\Contracts\Plugin class stubs
• tests/TestCase.php + tests/Fixtures/TestPanelProvider.php + tests/Pest.php
• CI workflows: branch-scoped tests.yml, plus pint.yml/phpstan.yml/update-changelog.yml covering every branch scaffolded
• git init, branch checkout(s), and a commit per branch

It deliberately does not write the plugin's actual logic (Plugin/Service Provider bindings, components, README body, tests, banner) — that's judgment work left to whoever (human or agent) is building the plugin on top of this scaffold.

Branch naming is always sequential (1.x, 2.x, 3.x, ...) — which Filament major each one targets is controlled separately via --filament-version/--to-filament-version, so a plugin doesn't have to start at Filament 3:

#Requirements

• PHP 8.2+
• Git

#Installation

composer global require jeffersongoncalves/filament-plugin-cli

Or clone and build locally:

git clone https://github.com/jeffersongoncalves/filament-plugin-cli.git
cd filament-plugin-cli
composer install
php filament-plugin app:build filament-plugin

#Usage

Scaffold a single starting branch targeting Filament 3 (the defaults — branch 1.x, --filament-version=3):

filament-plugin create jeffersongoncalves/filament-settings "Runtime settings panel for Filament"

Scaffold a single branch that starts straight at a later Filament major (e.g. the plugin never supported v3):

filament-plugin create jeffersongoncalves/filament-settings "Runtime settings panel for Filament" --filament-version=4

Scaffold every branch from Filament 3 through 5 in one go — 1.x→v3, 2.x→v4, 3.x→v5 (2.x built off 1.x, 3.x off 2.x):

filament-plugin create jeffersongoncalves/filament-settings "Runtime settings panel for Filament" --all-branches

Narrow the range — e.g. only 1.x→v3 and 2.x→v4 (stop before v5), or only 1.x→v4 and 2.x→v5 (skip v3 entirely):

filament-plugin create jeffersongoncalves/filament-settings "Runtime settings panel for Filament" --all-branches --to-filament-version=4
filament-plugin create jeffersongoncalves/filament-settings "Runtime settings panel for Filament" --all-branches --filament-version=4

Keywords and dependencies (the namespace already comes out right by default):

filament-plugin create jeffersongoncalves/filament-ban "Ban and unban any Eloquent model from Filament tables" \
  --keywords="laravel,filament,filament-plugin,ban,bannable" \
  --require="cybercog/laravel-ban:^4.10"

#Namespace

The default is the nested shape: the filament- prefix moves into its own segment, so the classes don't repeat it.

Both halves are studly-cased, which cannot see camel-case boundaries inside a single lowercase word (jeffersongoncalves → Jeffersongoncalves). Teach it once in ~/.package/vendornamespace.json, shared with laravel-package-cli:

{
    "jeffersongoncalves": "JeffersonGoncalves"
}

With that entry, jeffersongoncalves/filament-ban derives JeffersonGoncalves\Filament\Ban with no flags at all. Lookups are per whole slug and case-insensitive; unlisted slugs fall back to studly. See laravel-zero-package-scaffold for the file's full contract.

The config filename stays the full slug (config/filament-ban.php) to match spatie/laravel-package-tools' shortName().

Pass --namespace only to opt out — an older plugin on the flat JeffersonGoncalves\FilamentBan shape, or a one-off you don't want in the shared file.

Add a version branch to a plugin repo that already exists (the existing composer.json is kept — only the php, filament/filament and orchestra/testbench constraints move):

filament-plugin branch jeffersongoncalves/filament-settings --branch=2.x --filament-version=4 --path=./filament-settings --from=1.x

#create options

#branch options

Every argument/option is designed for scripted, non-interactive invocation — no prompts are ever shown.

Update the CLI to the latest release (PHAR installs only — Git/Composer installs must update via git pull/composer update):

filament-plugin self-update
filament-plugin self-update --check

#self-update options

#Testing

composer test

#Changelog

Please see CHANGELOG for more information on what has changed recently.

#Security

If you discover any security related issues, please see SECURITY.

#Credits

• Jefferson Goncalves
• All Contributors

#License

The MIT License (MIT). Please see License File for more information.