CLI

Create users, scaffold views and pages, run maintenance, and write your own commands from the terminal.

Updated
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.