README

The official command-line interface and code generators for the Velt framework.

Velt is in alpha. The CLI can create web and API projects; Android remains explicitly experimental until the native release gates pass.

Installation

Install the CLI globally to make velt available in your terminal:

composer global require velt/cli
velt list

Ensure Composer's global binary directory is in your PATH. bin/velt is the package entrypoint used internally by Composer; the supported user-facing command is always velt.

Commands

db:seed           Run database seeders
doctor            Check the web or Android development environment
kernel:check      Verify the application kernel
make:controller   Generate a controller
make:feature      Generate a feature module
make:migration    Generate a database migration
make:model        Generate a model
make:page         Generate a declarative page
make:seeder       Generate a database seeder
make:service      Generate a service
make:test         Generate a PHPUnit feature test
migrate           Run pending migrations
migrate:rollback  Roll back the last migration batch
new               Create and configure a new Velt project
serve             Start the local PHP development server

Run velt help <command> for the complete usage of a command.

Examples

velt new my-app
velt new backend --type=api --database=pgsql --no-interaction
velt new landing --type=web --styling=tailwind --database=sqlite --no-interaction
velt new mobile-suite --type=cross-platform --database=sqlite --no-interaction
velt doctor
velt doctor --profile=android
velt make:feature auth --no-interaction
velt make:controller UserController
velt make:model User
velt make:migration create_users_table
velt migrate
velt db:seed
velt serve --host=127.0.0.1 --port=8000

Generators never overwrite a file unless --force is supplied. Use --path=/path/to/project to target another application. serve --dry-run prints the PHP server command without starting a long-running process.

Project creation

velt new my-app asks for the project type, styling preset and database when used in an interactive terminal. CI and automation can provide every choice explicitly:

velt new my-app \
  --type=web \
  --styling=tailwind \
  --database=sqlite \
  --package-manager=npm \
  --no-interaction

Creation profiles are web, api and cross-platform. Web uses Tailwind by default, API removes all UI/frontend files, and cross-platform uses the portable Velt structure plus NativeWind assets. Use --skip-frontend to skip package installation/build, or --dry-run to inspect every command without writing files.

Android and universal profiles will only be exposed after the embedded PHP runtime, Compose renderer, signed APK pipeline and on-device tests are green.

Development

composer install
composer test
velt list

Composer exposes the internal bin/velt entrypoint as the global velt executable. Users should never need to type its repository path.

License

MIT

Command model

The CLI separates global project creation from commands executed against an existing application. velt new creates and configures a project; generators, migrations and the development server operate on the current directory unless --path selects another application.

Global options

velt --version
velt --help
velt list
velt help new

Commands return 0 on success and a non-zero status on validation, process or application errors. CI should use --no-interaction and provide every project choice explicitly.

Complete project-creation reference

velt new <name>
  --type=web|api|cross-platform
  --styling=tailwind|nativewind|none
  --database=sqlite|mysql|pgsql
  --package-manager=npm|pnpm|yarn|bun
  --path=/existing/parent
  --no-interaction
  --skip-frontend
  --dry-run

Creation performs the following transaction:

Validate the project name and writable parent directory.
Refuse an existing target to protect user files.
Clone the pinned public skeleton prerelease and install its dependencies through Composer. Once Packagist indexes the beta line, this becomes composer create-project again without changing the generated structure.
Run the skeleton profile configurator.
Re-resolve Composer dependencies after irrelevant packages are removed.
Install/build the selected style tool when required.
Print profile-specific next steps.

If a subprocess fails after creating the target, the CLI removes only that newly created project directory. It never removes a pre-existing target.

Profile behavior

Type	Style	Result
`web`	Tailwind default or none	Web routes/pages, HTTP, UI and data structure
`api`	Forced none	Backend routes/models/database; frontend and Preview removed
`cross-platform`	Forced NativeWind	Web/API/Preview plus portable native manifest and Android alpha dependencies

Cross-platform creation is experimental. It creates the correct source layout but does not mean the NativePHP/Compose runtime has passed device release gates.

Doctor reference

velt doctor
velt doctor --styling=none
velt doctor --package-manager=pnpm
velt doctor --profile=android
velt doctor --profile=android --json

Web checks cover PHP, JSON/PDO extensions, Composer, filesystem access and conditional Node/package-manager availability. Android adds PHP 8.4, Java, ADB, Android SDK, Gradle and 7zip checks. JSON output is suitable for setup scripts and CI diagnostics and intentionally excludes secret values.

Generators

velt make:feature Billing
velt make:controller InvoiceController
velt make:model Invoice
velt make:page Dashboard
velt make:service TaxCalculator
velt make:test InvoiceControllerTest
velt make:migration create_invoices_table
velt make:seeder InvoiceSeeder

Generators normalize names and namespaces, create parent directories and refuse overwrite unless --force is explicitly supplied. make:feature creates a cohesive page/controller/service/model/test module.

Database commands

velt migrate
velt migrate:rollback
velt db:seed
velt db:seed --class=DemoSeeder

These commands load the target application's bootstrap and delegate to velt/database; the CLI does not duplicate migration or query logic.

Development server

velt serve
velt serve --host=0.0.0.0 --port=8000
velt serve --host=127.0.0.1 --port=8080 --dry-run

Use 0.0.0.0 only when another device must reach the development computer. This server is for local development, not production deployment.

Architecture

bin/velt → ApplicationFactory → Application registry
                              ├─ Input parser
                              ├─ Output buffer/terminal
                              ├─ Command implementations
                              ├─ filesystem/template support
                              ├─ safe process runner
                              └─ project runtime adapter

Commands implement a small common contract with name, description, help and run. Filesystem and process behavior remain separate so creation and generators can be tested without starting network services.

CI and release validation

The repository tests PHP 8.2, 8.3 and 8.4 across Windows, Linux and macOS. The matrix runs manifest validation, installation, the PHPUnit suite, velt --version and dry-run creation of all three profiles.

Before tagging:

composer validate --strict
composer install --no-interaction --prefer-dist
composer test
velt new smoke-web --type=web --no-interaction --dry-run
velt new smoke-api --type=api --no-interaction --dry-run
velt new smoke-cross --type=cross-platform --no-interaction --dry-run

Stable promotion additionally requires an actual clean create-project smoke test against published packages, not only dry-run command construction.

Troubleshooting

velt is not found: add Composer's global binary directory to PATH and reopen the terminal.
Composer cannot resolve a component: confirm the requested prerelease stability and that every dependency tag exists.
Tailwind build fails: run velt doctor, check Node and the selected package manager, then retry from a clean node_modules installation.
Android checks fail: install PHP 8.4 and the Android SDK/JDK tools; a web-only project does not require them.
Target exists: choose a new project name. The CLI deliberately has no implicit overwrite mode for project roots.

Security and contribution

Project names and paths are validated before filesystem changes, native executables receive argument arrays, and cleanup is scoped to the newly created target. Windows .cmd/.bat package-manager wrappers are resolved explicitly and invoked through cmd.exe with escaped arguments because Windows cannot execute batch wrappers directly. Contributions adding external commands must preserve these properties and include failure/rollback tests.

velt / cli

Maintainers

Package info

Statistics

Security