- PHP 8.4 (minimum)
- Composer 2.x.x
The Assegai Console is the framework CLI for:
- creating new projects
- serving apps locally
- generating framework features
- exporting API contracts and clients
- working with queues, migrations, databases, and Web Components
- upgrading existing workspaces across supported framework release lines
It also supports custom schematics so teams can teach assegai generate about their own company-specific features.
For commit and pull request conventions in this repo, see:
Install the Assegai Console globally using Composer:
$ composer global require assegaiphp/consoleThen make sure Composer's global bin directory is on your PATH:
$ composer global config bin-dir --absoluteIf the printed directory is not already on your PATH, add it in your shell profile. For example:
$ export PATH="$PATH:$(composer global config bin-dir --absolute)"Refer to the official Composer documentation if your global Composer home is configured differently.
Update an existing global installation through the CLI itself:
$ assegai global update
# shorthand
$ assegai -g updateNormal commands perform a cached, short-timeout check for stable Console releases. When a newer version exists, the notice is written to stderr so command stdout remains safe for scripts and structured output. A successful check is reused for 24 hours, a failed check is retried after one hour, and an unavailable version service never prevents the requested command from running. Set ASSEGAI_NO_UPDATE_CHECK=1 when automatic checks must be disabled in a controlled environment.
The self-updater first ships with Console 0.10.1. It cannot be retrofitted into an older binary that is already installed. A release rollout that promises a fully self-service migration from an earlier Console must distribute an updater-enabled bridge or managed installer before asking those users to run this command.
To create a new Assegai project, run the following command:
$ assegai new my-appThis command will create a new Assegai project in the my-app directory.
The scaffold flow can also:
- initialize git
- configure a database
- write sensitive config to
config/secure.php - set up a starter users resource when ORM is enabled
After creating a new project, you can start the development server to preview your application in the browser.
$ cd my-appTo start the development server, navigate to the project directory and run the following command:
$ assegai serve
If you want to try the long-lived runtime path instead of the default PHP development server, install the OpenSwoole extension first and then run:
$ assegai serve --runtime=openswooleYou can also persist that choice in assegai.json:
{
"development": {
"server": {
"runtime": "openswoole",
"host": "127.0.0.1",
"port": 9510,
"openswoole": {
"workerNum": 1,
"taskWorkerNum": 0,
"maxRequest": 0,
"enableCoroutine": true,
"hookFlags": "all"
}
}
}
}If the extension is not installed, the CLI now stops early with a direct setup message instead of falling into a runtime bootstrap failure.
The current OpenSwoole path is still experimental. It is intended for careful testing and advanced runtime work, not as a blanket replacement for the default php runtime in every project.
The Console release determines the framework release line that assegai update can select. Composer constraints such as ^0.9.0 deliberately exclude 0.10, so update the globally installed CLI before asking it to migrate a 0.9 project:
$ assegai global update
# or: assegai -g update
$ assegai --version
$ assegai update --to=0.10 --dry-run
$ assegai update --to=0.10The dry run lists every direct requirement change and the Composer update set without changing files. A cross-release update then requires confirmation; non-interactive environments must pass --yes explicitly.
If the project itself requires assegaiphp/console:^0.9, do not try to upgrade that local dependency by itself. Run the globally installed 0.10 CLI so Core, the local Console requirement, and the other coordinated first-party packages move to 0.10 in one Composer transaction.
The command hydrates assegai.json, updates composer.json, and runs Composer with all dependent packages. It does not rewrite application PHP source or create config/auth.php. Review the update advisor for the application-owned configuration and verification steps. If Composer fails, the CLI restores assegai.json, composer.json, and composer.lock; run composer install if Composer changed vendor/ before failing.
Use assegai generate (or assegai g) to scaffold framework artifacts:
$ assegai g resource users
$ assegai g component app --flat
$ assegai g page dashboard --path src/AdminUseful options include:
--flatto generate directly into the target path instead of creating a name-based subdirectory--pathto place generated files at a source-relative path
Database-aware commands also support MySQL, MariaDB, PostgreSQL, SQLite, and MSSQL where applicable.
You can extend the generator without forking the CLI.
The default local convention is:
schematics/<name>/
schematic.json
templates/
Start with a declarative starter:
assegai schematic:init loyalty-programOr scaffold a PHP-backed starter when generation needs real logic:
assegai schematic:init customer-portal --phpInspect what the CLI discovered:
assegai schematic:listRun a custom schematic through the normal generate workflow:
assegai g loyalty-program rewardsFor reusable team schematics, package manifests can be exposed through composer.json:
{
"extra": {
"assegai": {
"schematics": [
"resources/loyalty/schematic.json"
]
}
}
}Learn more in the official documentation.
- Author - Andrew Masiye, Daniel Kaluba
- Website - https://assegaiphp.com
- X - @assegaiphp
Assegai Console is MIT Licensed