Cli Laravel Package

Getting Started

You almost never install laravel-enso/cli directly. It arrives as a transitive dependency of laravel-enso/enso (or the core metapackage), so start by confirming it is present:

composer show laravel-enso/cli
php artisan list enso

That second command is the fastest way to see what surface area you actually have — the package registers a family of enso:* commands rather than a single entry point. In a fresh project the practical first use case is structural bootstrapping:

# after the DB is configured and APP_KEY is set
php artisan enso:install      # publish config/assets, wire up structure
php artisan enso:migrate      # run Enso-owned migrations
php artisan enso:seed         # seed roles, permissions, menus, default user

Treat enso:install as the "one-time" command and enso:migrate / enso:seed as the repeatable ones you will actually run day to day.

Where to look first:

• vendor/laravel-enso/cli/src/Commands — this is the real reference; the README is thin and the commands are self-documenting.
• config/enso/ — published config for the broader Enso stack; CLI behaviour usually reads from there rather than having its own config file.
• php artisan enso:<command> --help — signatures, options, and argument order are worth skimming before scripting anything.

Implementation Patterns

Deployment hook, not a manual step. The most common use is in a deploy script, running after composer install and before the app is hit by traffic:

php artisan migrate --force
php artisan enso:update        # pull new structure from updated packages
php artisan enso:permissions   # sync permission definitions
php artisan config:cache

The ordering matters — structure commands assume the schema exists, so run enso:update after the base migrations, not before.

Structuring new models. If you are building CRUD resources on top of Enso, use the CLI's generators rather than hand-rolling models. The Enso model generator wires up the traits and structure conventions (table naming, timestamps, permission registration) that the rest of the admin UI expects. A model that skips these will render but will not appear in the menu/permission system correctly.

php artisan enso:model Invoice
# then edit the generated migration, add relations, and run enso:migrate

Scaffolding as a workflow, not a shortcut. The generator is best used as a starting point you immediately edit, not a finished artifact. The cycle is: generate → edit migration → enso:migrate → enso:seed (or run the specific structure seeder) → verify in the UI. Skipping the seed step is the most common reason a new resource "doesn't show up."

Wrapping commands in your own Artisan command when you need orchestration — for example, a app:provision-tenant command that calls the Enso commands programmatically via $this->call('enso:migrate'). This keeps the Enso package untouched while giving you a single stable entry point for CI and ops.

Integration with package upgrades. After composer update, run enso:update rather than plain migrate. It knows about Enso-specific structural changes (menu entries, permission renames) that a raw migration pass will miss.

Gotchas and Tips

• It is not standalone. The commands assume the Enso core packages are installed and configured. Running enso:install in a bare Laravel app will fail or leave a half-wired structure. If you only want the CLI's generators, install the full Enso stack instead — this package is not designed to be cherry-picked.

• Version pin to the Enso release. The CLI's commands track the Enso structure schema. A CLI version mismatch against laravel-enso/enso produces confusing failures ("column not found" in structure seeding) rather than a clear version error. Use the same constraint as the rest of the Enso packages, ideally the metapackage's own lockfile.

• Commands are not all idempotent. enso:install in particular is a one-shot; re-running it can duplicate permissions or menus. enso:update, enso:migrate, and enso:permissions are the ones safe to repeat in a deploy script. When in doubt, check whether the command has a --force flag — if it does, the default (non-forced) behaviour is the careful one.

• Ordering bugs are silent. Permissions referencing a model class that hasn't been migrated yet will fail during enso:seed with a class-not-found or a foreign-key violation. If you see this, run enso:migrate first and re-run the seed; don't start editing seeders.

• config:cache can hide new structure config. After adding a package or editing config/enso/, run php artisan config:clear before expecting the CLI to pick up the change. This is standard Laravel but bites hard here because the CLI reads structural config at boot.

• Debug with -vvv. The commands suppress a lot of output; php artisan enso:update -vvv shows the underlying Artisan calls and the SQL, which is usually enough to diagnose a failure without reading the package source.

• Extension points are thin. There is no event system or hook registry specific to the CLI. If you need custom behaviour, the intended pattern is to wrap the commands in your own Artisan command or a service provider, not to extend the package's command classes. Treat it as a set of scripts, not a framework.

• Low maintenance signal. With a small star count and a single-maintainer history, treat each composer update as a potential breaking change for this package specifically. Pin it, and read the changelog before bumping — the blast radius if it breaks is your whole admin structure.