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

composer global require getkirby/cli

Make sure to add your composer bin directory to your ~/.bash_profile (Mac OS users) or into your ~/.bashrc (Linux users).

Your global composer directory is normally either ~/.composer/vendor/bin or ~/.config/composer/vendor/bin. You can find the correct path by running …

composer -n config --global home

Afterwards, add the result to your bash profile …

export PATH=~/.composer/vendor/bin:$PATH

Check if the installation worked by running the following in your terminal.

kirby

This should print the Kirby CLI version and a list of available commands

- kirby backup
- kirby clean:content
- kirby clear:cache
- kirby clear:lock
- kirby clear:logins
- kirby clear:media
- kirby clear:sessions
- kirby download
- kirby help
- kirby install
- kirby install:kit
- kirby install:repo
- kirby license:info
- kirby license:renewal
- kirby make:blueprint
- kirby make:collection
- kirby make:command
- kirby make:config
- kirby make:controller
- kirby make:language
- kirby make:model
- kirby make:plugin
- kirby make:snippet
- kirby make:template
- kirby make:user
- kirby migrate:to:public-folder
- kirby migrate:to:root-folder
- kirby plugin:install
- kirby plugin:remove
- kirby plugin:upgrade
- kirby register
- kirby remove:command
- kirby roots
- kirby security
- kirby unzip
- kirby upgrade
- kirby uuid:duplicates
- kirby uuid:generate
- kirby uuid:populate
- kirby uuid:remove
- kirby version

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.

You can also define commands as classes. Your custom command class must extend the built-in Kirby\CLI\Command class:

use Kirby\CLI\CLI;
use Kirby\CLI\Command;

class HelloWorld extends Command
{
	public static function args(): array
	{
		return [
			// optional args
		];
	}

	public static function command(CLI $cli): void
	{
		$cli->out('Hello world');
	}

	public static function description(): string|null
	{
		return 'The infamous hello world example';
	}
}

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.

To load a custom environment config for a particular host, you can set an env variable

env KIRBY_HOST=production.com kirby mycommand

Your Kirby plugins can define their own set of commands: https://getkirby.com/docs/reference/plugins/extensions/commands

Kirby::plugin('your/plugin', [
	'commands' => [
		'your-plugin:test' => [
			'description' => 'Nice command',
			'args' => [],
			'command' => function ($cli) {
				$cli->success('My first plugin command');
			}
		]
	]
]);

use Kirby\CLI\CLI;
use Kirby\CLI\Command;

class HelloWorld extends Command
{
	public static function args(): array
	{
		return [
			// optional args
		];
	}

	public static function command(CLI $cli): void
	{
		$cli->out('Hello world');
	}

	public static function description(): string|null
	{
		return 'The infamous hello world example';
	}
}

Kirby::plugin('your/plugin', [
	'commands' => [
		'helloworld' => HelloWorld::class
	]
]);

You can always check back if your commands have been created properly by running kirby again

kirby

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.

Use the -d or --debug argument to run the command in debug mode:

kirby make:command hello --debug

Sending messages to the terminal is super easy.

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

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

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

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

// 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/

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.

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

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 . '!');
    }
];

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/

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');
    }
];

• getkirby.com – Get to know the CMS.
• Try it – Take a test ride with our online demo. Or download one of our kits to get started.
• Documentation – Read the official guide, reference and cookbook recipes.
• Issues – Report bugs and other problems.
• Feedback – You have an idea for Kirby? Share it.
• Forum – Whenever you get stuck, don't hesitate to reach out for questions and support.
• Discord – Hang out and meet the community.
• YouTube - Watch the latest video tutorials visually with Bastian.
• Mastodon – Spread the word.
• Bluesky – Tell a friend.

© 2009 Bastian Allgeier getkirby.com · License agreement