README.md

Kirby CLI

The Kirby command line interface helps simplifying common tasks with your Kirby installations.

Installation

composer global require getkirby/cli

Available commands

- kirby clear:cache
- kirby clear:media
- kirby clear:sessions
- kirby download
- kirby help
- kirby install
- kirby install:kit
- kirby install:repo
- kirby make:blueprint
- kirby make:collection
- kirby make:command
- kirby make:config
- kirby make:controller
- kirby make:model
- kirby make:plugin
- kirby make:snippet
- kirby make:template
- kirby remove:command
- kirby unzip
- kirby uuid:generate
- kirby uuid:populate
- kirby version

Listing commands

If you need a nice overview of all available commands you can simply run …

kirby

… without any additional arguments. This will not just show you the built-in commands, but also the globally and locally installed commands on your machine.

Writing commands

You can create a new command via the CLI:

kirby make:command hello

This will create a new site/commands folder in your installation with a new hello.php file

The CLI will already put the basic scaffolding into the file:

<?php

return [
    'description' => 'Nice command',
    'args' => [],
    'command' => static function ($cli): void {
        $cli->success('Nice command!');
    }
];

You can define your command logic in the command callback. The $cli object comes with a set of handy tools to create output, parse command arguments, create prompts and more.

Output

Sending messages to the terminal is super easy.

$cli->out()

$cli->out('This is some simple text');

$cli->success()

$cli->success('This is text in a nice green box');

$cli->error()

$cli->error('This is red text for errors');

$cli->bold()

$cli->bold('This is some bold text');

$cli->br()

// this will create a line break
$cli->br();

For more available colors and formats, check out the CLImate docs: https://climate.thephpleague.com/styling/colors/

Arguments

Your commands can define a list of required and optional arguments that need to be provided by the user.

<?php

return [
    'description' => 'Hello world',
    'args' => [
        'name' => [
            'description' => 'The name for the greeting',
            'required'    => true
        ]
    ],
    'command' => static function ($cli): void {
        $cli->success('Hello ' . $cli->arg('name') . '!');
    }
];

The command can now be executed by providing the name …

kirby hello Joe

If no name is provided, an error will be shown.

Argument docs

Arguments can be required, can set a default value and more. Check out the CLImate docs for additional options: https://climate.thephpleague.com/arguments/

Prompts

Instead of taking arguments from the command, you can also ask for them in a prompt:

<?php

return [
    'description' => 'Hello world',
    'command' => static function ($cli): void {
        $name = $cli->prompt('Please enter a name:');
        $cli->success('Hello ' . $name . '!');
    }
];

As a third alternative you can either take the argument or ask for it if it is not provided:

<?php

return [
    'description' => 'Hello world',
    'args' => [
        'name' => [
            'description' => 'The name for the greeting',
        ]
    ],
    'command' => static function ($cli): void {
        $name = $cli->argOrPrompt('name', 'Please enter a name:');
        $cli->success('Hello ' . $name . '!');
    }
];

Checkboxes Radios and more

The CLI also supports more complex ways to get input from users. Check out the CLImate docs how to work with user input: https://climate.thephpleague.com/terminal-objects/input/

Combining commands

You can reuse all existing commands in your custom commands to create entire chains of actions.

<?php

return [
    'description' => 'Downloads the starterkit and the plainkit',
    'command' => static function ($cli): void {

        $cli->command('install:kit', 'starterkit');
        $cli->command('install:kit', 'plainkit');

        $cli->success('Starterkit and plainkit have been installed');
    }
];

Global commands

You might have some commands that you need for all your local Kirby installations. This is where global commands come in handy. You can create a new global command with the --global flag:

kirby make:command hello --global

The command file will then be place in ~/.kirby/commands/hello.php and is automatically available everywhere.

Removing commands

Once you no longer need a command, you can remove it with …

kirby remove:command hello

If you have a local and a global command, you can choose which one to delete.

kirby.cli.json

You can place a kirby.cli.json file in root folder of your project to setup the Kirby instance with custom directories. This is useful if you use a non-standard Kirby installation with a public webroot for example.

{
    "roots": {
        "index": "./public",
    }
}

Where to place local commands

The config can also set where local commands are stored. By default, they are stored in /site/commands

{
    "roots": {
        "commands.local": "./commands",
        "commands.global": "/var/kirby/commands",
    }
}