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
pinx migrate                  # uses DevDB in development by default
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: pinx doctor reports PHP, layout, env, DB, and build readiness.

To turn an existing app folder into the single-app layout:

cd existing-app
pinx repair --package=com_vendor_app
pinx migrate
pinx dev

Use pinx sync when you only want to add missing template support files. Use pinx sync --force or pinx repair --force only when you intentionally want template-managed support files overwritten.

Pinx Inspector is available automatically while pinx dev is running:

pinx dev
# open http://127.0.0.1:8000/~inspector

Pinx Inspector is provided by pinoox/pinx-inspector and should be installed in require-dev:

composer require --dev pinoox/pinx-inspector

Use pinx dev --no-inspector to disable it, or pinx inspector as a standalone fallback when the app server is not running. Inspector is local-only and works without Node, npm, Electron, or extra setup.

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
pinx migrate
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          # quick one-line version
pinx version     # version, install path, and update check
composer global update pinoox/pinx-cli # upgrade global pinx install
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 db:list                # platform + app connections (--test, --json)
pinx db:show platform       # connection details
pinx db:test                # probe connectivity

pinx user:create admin --password=secret --role=admin
pinx role:list
pinx permission:list
pinx token:list
pinx file:list

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       Connections, 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
Users          Create and manage app users from CLI
Roles & permissions  Manage roles and permission keys
Tokens         Session tokens and API keys
Files          Uploaded files and storage records
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

Users

Roles & permissions

Tokens

Files

Pinion (resumable uploads)

Forwarded to php pinoox pinion:* — temp chunked upload sessions under storage/pinion.

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
php bin/pinx doctor
php bin/pinx migrate
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.2 with extensions required by pinoox/pincore
• Composer 2.x
• Node.js + npm — only when using Vite/Vue/React frontends
• Database - DevDB for local development by default; MySQL/MariaDB/PostgreSQL/SQLite when configured in .env

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.