CLI
Create users, scaffold views and pages, run maintenance, and write your own commands from the terminal.
On this page
Running commands
The CLI is at phlat/addons/cli/. Run it from anywhere in the project:
php phlat/addons/cli/phlat <command> [args] [--flags]
php phlat/addons/cli/phlat help
composer exec phlat -- <command> also works. The examples below write the command as phlat.
phlat help # every command, grouped by namespace
phlat help make # one namespace
phlat make:page --help # one command
Commands run without addons loaded. They read and write site/pages/ and site/data/ directly, and site/data/env.cli.json is merged over site/data/env.json.
Accounts
phlat user:create adam --role=admin
phlat user:list
phlat user:password adam
phlat user:role adam editor
phlat user:delete adam
The password is prompted for, hidden, unless you pass --password=.
Scaffolding
phlat make:view article
phlat make:field summary --type=text --label=Summary
phlat make:page blog/first-post --view=article --title="First post"
make:view creates site/views/article/. make:field writes a field definition to site/fields/; its --type defaults to @phlat/text. To assign a field to a view, list it under fields in the view's index.json. make:page creates the page folder under site/pages/ with a minted uuid.
Pages
phlat page:list 'view=article,sort=-updated'
phlat page:field blog/first-post title # read a field
phlat page:field blog/first-post title "New title" # set it
phlat page:publish blog/first-post --off
phlat page:access members --to=login
phlat page:move blog/first-post news/first-post
phlat page:delete blog/first-post
page:list takes the same query DSL as $app->find(). page:access takes public, login, or role names joined by |. Moves and deletes keep the registry in sync.
Maintenance
| Command | Does |
|---|---|
backup:create / backup:restore |
Back up or restore pages (collections included), users, git/ and the env files |
registry:check / registry:rebuild |
Report invalid or duplicate UUIDs, or re-scan site/pages into the registry |
files:rebuild |
Sweep stale variants out of site/public/ |
files:fix |
Rename managed files whose names fall outside the URL grammar. A dry run until --apply |
cache:clear |
Clear one named cache, one page's cached output (--page=<path>, plus --tree for what a save of it clears), or empty site/data/cache |
throttle:clear |
Reset the login throttle, so a locked-out IP can try again |
key:generate |
Make the site's encryption key and save it as app.key in site/data/env.json. It refuses to replace one unless --force is given |
env:set |
Set a key in site/data/env.json with dot notation, such as env:set url https://example.com. A valid JSON value keeps its type (true, 3), anything else is text. It refuses a file that is not valid JSON |
env:get |
Print a key from site/data/env.json, and exit 1 when it is not set |
@totp:reset |
Turn off a user's one-time codes and end their sessions, for a lost authenticator |
db:backup / db:vacuum |
Snapshot every collection's database, or compact every SQLite database, merging full-text indexes first |
collection:migrate |
Move items from the old per-item folders into their collection's database. A dry run until --apply; back up first |
collection:prune |
Delete the items of a collection field that match --where=<query>, files included. --dry-run reports only, --force skips the prompt |
collection:reindex |
Redo a collection's search tables after its field's options change |
page:dates |
Rewrite ISO date strings in pages and users as Unix timestamps. Lists what it would change until --apply; run registry:rebuild after |
user:migrate |
Move user folders from data/users/{username} to data/users/{shard}/{uuid}. Run registry:rebuild after |
health:check |
Diagnose the SQLite version, database integrity, page tree, file caches, env.json and permissions. Exits 1 on any issue, so it works as a deploy gate |
health:disk |
Disk usage of each folder in site/data/ |
uuid:generate / uuid:regenerate |
Mint a uuid, or reassign every page and user uuid |
tools:uuid |
Print a random UUID-style hash |
clockwork:clear / clockwork:prune / clockwork:status |
Manage the profiler database |
addons:list / addons:install / addons:update / addons:uninstall / addons:reset |
List addons, and manage those installed as pinned git submodules under site/addons/ |
Writing a command
A command is a PHP file with $app and $args in scope. Its path is its name: commands/make/page.php is make:page. Site commands go in site/commands/; reusing a built-in name is a hard error. An addon's commands/ folder is prefixed with the addon alias, so site/addons/newsletter/commands/send.php runs as @newsletter:send.
Lead with a docblock. Its first line is the summary in phlat help, and the rest is the --help text:
<?php
declare(strict_types=1);
/** @var \Phlat\App $app */
/** @var array $args */
/**
* Print the number of pages.
*
* Usage: phlat page:count [query]
*
* query Registry query, e.g. view=article
*/
use Phlat\Toolkit\Cli;
if (Cli::wantsHelp($args)) {
Cli::usage(__FILE__);
}
Cli::out((string) $app->find($args[0] ?? '')->count());
Use Cli for all output: out, info, success, warning, error, table, progress, input and confirm.