README

The developer CLI for single-app Pinoox projects — scaffold, run, migrate, build, and ship .pinx packages without touching a multi-app manager.

Built on pinoox/pincore and the pinoox/app template. Your project root is the app: one app.php, one package, one workflow.

Quick start

Install Pinx once, create a new app, run it:

composer global require pinoox/pinx-cli

pinx new my-shop              # suggests com_my_shop — confirm or edit in the wizard
cd my-shop
cp .env.example .env          # set DB_* if you use a database
pinx setup                    # migrate platform + app, run seeders
pinx dev                      # http://127.0.0.1:8000

Add Composer’s global bin to your PATH if pinx is not found:

• Linux / macOS: ~/.composer/vendor/bin or ~/.config/composer/vendor/bin
• Windows: %APPDATA%\Composer\vendor\bin

Package names follow com_{vendor}_{name} — e.g. com_acme_shop, ir_yekdo_app. Already inside an empty folder? Use pinx init instead of pinx new.

Optional check before setup: pinx doctor reports PHP, layout, env, DB, and build readiness.

Alternative: composer create-project

No global install — the template ships with bin/pinx inside the project:

composer create-project pinoox/app my-shop
cd my-shop
cp .env.example .env
pinx setup
pinx dev

What makes single-app different

Classic Pinoox installs keep many apps under apps/ and pick one at runtime. Single-app flattens that:

• app.php at the project root holds package identity and pinx settings
• Controller/, Model/, routes/, theme/ live at the root — not inside apps/{package}/
• platform/ holds local routing and launcher config (excluded from .pinx builds)
• Pinx always targets your app — no package picker, no manager UI

my-shop/                    ← project root = app root
├── app.php                 ← package, version, pinx.sign, frontend.stack
├── Controller/ Model/ routes/ theme/
├── platform/               ← dev host + deploy layer (local only)
├── bin/pinx                ← project-local CLI entry
└── vendor/pinoox/pincore   ← framework

See the pinoox/app README for the full layout and config layers.

Installation

pinx -v          # CLI version (e.g. pinx-cli 1.1.7)
pinx list        # grouped command overview
pinx help setup  # detail for one command

Day-to-day workflow

pinx dev                    # local server (+ Vite when app.php → frontend.stack is set)
pinx dev --open             # open browser after start
pinx dev --no-frontend      # PHP only

pinx migrate                # run app migrations (--platform runs platform first)
pinx migrate:st             # migration status
pinx migrate:cr create_products_table

pinx make controller ProductController
pinx make model ProductModel
pinx make migration create_products_table
pinx make portal ShopService

pinx routes                 # list named actions (--validate, --json)
pinx test                   # run app tests (Pest)

Frontend (when theme/ uses Vue/React + Vite):

pinx fe:info                # stack, npm scripts, paths
pinx fe:i                   # npm install
pinx fe:d                   # Vite dev server
pinx fe:b                   # production build
pinx fe:sc --stack=vue      # scaffold starter files

Dependencies:

pinx deps:st                # Composer + npm status
pinx deps:i                 # install all
pinx deps:up                # update all

Pinker (build cache):

pinx pinker:st              # cache vs source
pinx pinker:rb              # rebuild
pinx pinker:df              # diff

Ship to production

Build a .pinx package for installation on a full Pinoox platform (Manager → Applications):

pinx build                  # → export/*.pinx
pinx build -o /tmp/shop.pinx
pinx release --bump=patch   # bump version in app.php + build
pinx release --sign         # sign when key is configured in app.php → pinx.sign

pinx build applies sensible defaults (excludes vendor/, bin/, .env, platform/, dev tooling). Override in app.php only when needed:

'build' => [
    'exclude' => ['my-private-notes/'],
    'composer' => false,
],
'pinx' => [
    'sign' => [
        'enabled' => false,
        'key' => null,
        'key_id' => null,
    ],
],

App detection

Pinx walks up from the current working directory until it finds a valid single-app project:

1. app.php exists and returns an array with a non-empty package key
2. pinoox/pincore is required in composer.json, or vendor/pinoox/pincore / a local pincore/ clone is present

Override the detected package with environment variables:

The package can also be resolved from platform/apps.config.php when the app is registered with path ~.

pinx list — grouped commands

Run pinx list for a sectioned overview. Shorthand aliases appear in brackets. Filter by prefix or use --short for names only.

Project        Scaffold and inspect the single-app project
Development    Local server and day-to-day workflow
Database       Migrations and seeders
Patches        Data patches and one-off app updates
Build & release  Package and ship .pinx artifacts
Scaffolding    Generate controllers, models, tests, and more
Routes         Named actions and route diagnostics
Dependencies   Composer and npm dependency tooling
Frontend       Theme assets, Vite, and npm scripts
Schedule       Cron tasks from schedule.php
Pinker         Build cache and override management
Quality & docs Tests and API documentation

Examples:

pinx list
pinx list migrate
pinx list --short
pinx list --raw

Command reference

Project

Development

Database

Patches

Build & release

Scaffolding

Routes

Dependencies

Legacy umbrella commands deps and dep still accept status, install, update as the first argument.

Frontend

Legacy frontend / fe accept info, install, build, dev, scaffold as the first argument.

Schedule

Pinker

Quality & docs

Meta

pinx doctor in depth

Doctor runs a structured diagnostic and suggests fix commands when something fails:

pinx doctor
pinx doctor --skip-db
pinx doctor --json          # CI-friendly report
pinx doctor --no-fixes      # hide suggested commands

Monorepo development

When working inside the pinoox/pinoox repository, pinx new resolves the template from packages/app automatically.

cd packages/pinx-cli
composer install

# scaffold a throwaway app (skip install to wire path repos yourself)
php bin/pinx new ../tmp-my-app --package=com_demo_shop --no-install

cd ../tmp-my-app
composer config repositories.pinx-cli path ../pinx-cli
composer require pinoox/pincore pinoox/pinx-cli:@dev
cp .env.example .env
php bin/pinx doctor
php bin/pinx setup
php bin/pinx dev

After composer install on a platform checkout, apply the pincore overlay for DevApp and improved pinx:build:

php packages/apply-pincore-overlay.php

Requirements

• PHP ≥ 8.1 with extensions required by pinoox/pincore
• Composer 2.x
• Node.js + npm — only when using Vite/Vue/React frontends
• Database — MySQL/MariaDB or whatever your .env configures (optional for static/Twig-only apps)

Related packages

Publish targets: composer global require pinoox/pinx-cli · composer create-project pinoox/app · enable Template repository on github.com/pinoox/app.

License

MIT — see composer.json.