Skip to content

Console

Belikhun edited this page Sep 15, 2026 · 1 revision

⌨️ Console

Blink ships a console entry at core/blink. It boots the same setup.php a web request does, minus the request handling, then dispatches to a command.

php core/blink list
php core/blink help ticker:run
php core/blink terra:apply --force
php core/blink --root=/var/www/site ticker:run

Hosts that only run .php files can use core/cli.php in its place.

The site a command belongs to is found from, in order: --root=, the BLINK_ROOT environment variable, the working directory when it holds config.define.php, and finally the directory above blink.

Writing a command

namespace App\Console;

use App\Model\Order;
use Blink\Console;
use Blink\Console\Command;

class ImportOrders extends Command {
	public static string $usage = "orders:import {file : Path to the CSV} {--dry-run : Parse without writing} {--c|chunk=500 : Rows per insert}";

	public static string $description = "Import orders from a CSV export";

	public function run(Importer $importer) {
		$path = $this -> argument("file");
		$chunk = (int) $this -> option("chunk");

		if (!file_exists($path)) {
			$this -> error("No such file: {$path}");
			return Console::EXIT_FAILURE;
		}

		if (!$this -> option("dry-run") && !$this -> confirm("Import into " . Order::$table . "?", true))
			return Console::EXIT_OK;

		$count = $importer -> import($path, $chunk, dryRun: (bool) $this -> option("dry-run"));

		$this -> success("Imported {$count} order(s).");
		return Console::EXIT_OK;
	}
}

A module lists it in commands(), and it is available at once.

The usage line

$usage names the command and everything it takes in one line:

Token Meaning
{name} A required argument
{name?} An optional argument
{name=default} An argument with a default
{name*} The last argument swallows everything remaining
{--flag} A boolean option
{--opt=} An option that takes a value, no default
{--opt=10} An option with a default
{--o|opt} An option with a short form
{... : text} A description shown by help

$usage and $description are static so list and help never instantiate a command whose constructor touches the database.

Inside run()

run() is called through Essence, so it can type-hint services. Its return value is the exit code; nothing means 0.

Helper Does
argument($name), option($name) Read the parsed input; without a name, everything
line(), info(), success(), warning(), comment() Write to stdout, colored when it is a terminal
error() Write to stderr, so real output stays pipeable
heading($text) A title with a rule under it
table($headers, $rows) An aligned table
confirm($question, $default) A yes/no prompt; returns the default when stdin is not a terminal

Exit codes

Constant Value Meaning
Console::EXIT_OK 0 Done
Console::EXIT_FAILURE 1 The command failed
Console::EXIT_USAGE 2 Bad arguments, or no such command
Console::EXIT_MEMORY 12 Stopped at the memory ceiling
Console::EXIT_INTERRUPTED 130 Stopped by a signal
Console::EXIT_FATAL 255 PHP died

An unknown command exits 2 and suggests near matches. A command that throws exits 1: the exception is stored as an error report, the same one a failed web request would get, and its summary, stack trace and report id are printed to stderr. error:list finds it later.

Calling a command from code

Console::call("terra:apply", array( "--force" ));

Returns the exit code and writes to the console's output, or to an Output you pass as the third argument.

The built-ins

Group Commands
list, help, about, cache:clear, route:list
errors error:list, error:purge
locks lock:list, lock:release
terra terra:apply, terra:status, terra:revert, terra:reset, terra:rebuild, terra:make
ticker ticker:run, ticker:tick, ticker:orbits, ticker:status, ticker:failed, ticker:retry, ticker:forget, ticker:clear, ticker:restart
lightrail lightrail:listeners, lightrail:dispatch, lightrail:retry, lightrail:flush, lightrail:purge
trace trace:list, trace:purge

help <command> prints any command's arguments and options.

CLI mode

Under the console, setup.php skips path parsing, output buffering, session start and routing; it sets set_time_limit(0) and ignore_user_abort(true), raises the memory limit to CONFIG::$CLI_MEMORY_LIMIT when the current one is lower, and swaps the HTML error page for a text renderer on stderr. Terra's auto-apply does not run under the console: the operator can run terra:apply and read what it says.

Clone this wiki locally