Kirby CLI
The Kirby command line interface helps simplifying common tasks with your Kirby installations., (*1)
Installation
Via Composer
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)., (*2)
Your global composer directory is normally either ~/.composer/vendor/bin or ~/.config/composer/vendor/bin. You can find the correct path by running …, (*3)
composer -n config --global home
Afterwards, add the result to your bash profile …, (*4)
export PATH=~/.composer/vendor/bin:$PATH
Did it work?
Check if the installation worked by running the following in your terminal., (*5)
kirby
This should print the Kirby CLI version and a list of available commands, (*6)
Available core 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 plugin:install
- kirby plugin:remove
- kirby plugin:upgrade
- kirby register
- kirby remove:command
- kirby roots
- kirby security
- kirby unzip
- kirby upgrade
- kirby uuid:generate
- kirby uuid:populate
- kirby uuid:remove
- kirby version
Writing commands
You can create a new command via the CLI:, (*7)
kirby make:command hello
This will create a new site/commands folder in your installation with a new hello.php file, (*8)
The CLI will already put the basic scaffolding into the file:, (*9)
<?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., (*10)
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:, (*11)
kirby make:command hello --global
The command file will then be place in ~/.kirby/commands/hello.php and is automatically available everywhere., (*12)
Command environment
To load a custom environment config for a particular host, you can set an env variable, (*13)
env KIRBY_HOST=production.com kirby mycommand
Command plugins
Your Kirby plugins can define their own set of commands: https://getkirby.com/docs/reference/plugins/extensions/commands, (*14)
Kirby::plugin('your/plugin', [
'commands' => [
'your-plugin:test' => [
'description' => 'Nice command',
'args' => [],
'command' => function ($cli) {
$cli->success('My first plugin command');
}
]
]
]);
Check for installed commands
You can always check back if your commands have been created properly by running kirby again, (*15)
kirby
Removing commands
Once you no longer need a command, you can remove it with …, (*16)
kirby remove:command hello
If you have a local and a global command, you can choose which one to delete., (*17)
Debugging
Use the -d or --debug argument to run the command in debug mode:, (*18)
kirby make:command hello --debug
Sending messages to the terminal is super easy., (*19)
$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/, (*20)
Arguments
Your commands can define a list of required and optional arguments that need to be provided by the user., (*21)
<?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 …, (*22)
kirby hello Joe
If no name is provided, an error will be shown., (*23)
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/, (*24)
Prompts
Instead of taking arguments from the command, you can also ask for them in a prompt:, (*25)
<?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:, (*26)
<?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/, (*27)
Combining commands
You can reuse all existing commands in your custom commands to create entire chains of actions., (*28)
<?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');
}
];
What's Kirby?
-
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, (*29)
Wallogit.com
