Exploring the Craft CMS 3 Console Command Line Interface (CLI)
Craft CMS 3 comes with many useful commands that can save you time, and make your life easier. In this article, you’ll learn how to stop worrying and love the CLI
Andrew Welch / nystudio107
The commands in this article are current as of Craft CMS 3.3.16.1
Craft CMS 3 comes with a wonderful console command line interface (CLI), but some people fear CLI’s in general, and others may not fully appreciate what the Craft CLI can do for you. Fortunately, the best way to overcome both is through understanding.
This article goes into depth explaining what the Craft CLI is, and details the commands that are available to you. So let’s dive right in!
When might we want to use the Craft CLI?
To fully appreciate why the Craft CLI can be so useful, we need to understand a bit about how it works, and how regular web requests work.
For a regular web request, the web server handles the request, handing off the processing of PHP to a separate process (usually php-fpm). Craft CMS is written in PHP, and also the Twig templates we write are compiled down to PHP.
So suffice it to say that for any given web request, there will typically be a fair bit of PHP that ends up running on our web server. Since web requests are external, untrusted requests there is a memory_limit and a max_execution_time for each request, so that our server is not overwhelmed.
While this is normally wonderful, when we need to perform intensive operations like multiple image transforms, re-saving of entries, and especially Craft CMS & plugin updates, it can become a hinderance. Timeouts happen, queue jobs fail, and it’s no fun for anyone.
Additionally, when we have occasion to run tasks at regular intervals or when we deploy changes to our website, doing things like going in and clearing caches by hand gets old quick.
The Craft CMS console command line interface to the rescue:
- Tasks run via CLI typically have no memory_limit or max_execution_time, because they are run by an internal, trusted source, so you they won’t timeout or run out of memory
- CLI tasks can easily be triggered at regular intervals (perhaps via cron) or triggered when certain events happen, in an automated way that doesn’t require any user intervention
So for any time consuming or memory intensive process, as well as whenever we need tasks to happen in an automated way, the CLI is our friend.
What exactly is the Craft CLI?
Now that we know when we might want to use the Craft CLI, let’s have a peek behind the curtains to see exactly what it is.
When we set up a new Craft CMS 3 project, there are a couple of curious files that are placed in the project root directory:
-rwxr--r-- 1 vagrant vagrant 501 Nov 17 2017 craft
-rwxr--r-- 1 vagrant vagrant 330 Apr 15 2017 craft.bat
The craft.bat file is just a wrapper for running Craft CLI on Windows, it ends up running the craft command in the end. So let’s have a look at what the craft command is, exactly:
#!/usr/bin/env php
<?php
/**
* Craft console bootstrap file
*/
// Set path constants
define('CRAFT_BASE_PATH', __DIR__ );
define('CRAFT_VENDOR_PATH', CRAFT_BASE_PATH.'/vendor');
// Load Composer's autoloader
require_once CRAFT_VENDOR_PATH.'/autoload.php';
// Load dotenv?
if (file_exists(CRAFT_BASE_PATH.'/.env')) {
(new Dotenv\Dotenv(CRAFT_BASE_PATH))->load();
}
// Load and run Craft
define('CRAFT_ENVIRONMENT', getenv('ENVIRONMENT') ?: 'production');
$app = require CRAFT_VENDOR_PATH.'/craftcms/cms/bootstrap/console.php';
$exitCode = $app->run();
exit($exitCode);
The first line #!/usr/bin/env php is called a shebang (this was a thing long before Ricky Martin) which essentially just tells the console that the script is PHP, and to execute in the current environment.
The rest of the code is very similar to what is in our web/index.php, which makes sense, because we’re running Craft in both cases. Just think of the craft command as the CLI equivalent of the web’s index.php. Both bootstrap Craft, and run it.
Running things in the Craft CLI
To execute the Craft CLI in its simplest form, make sure you’re in the root directory of your project in your console (perhaps using the cd command) and type:
./craft
The odd looking ./ is a Unix-ism that means “in this current directory”. I know, I know. You’re already in that current directory, why doesn’t it know this already? Just accept it and let it happen, because if we don’t use it we’ll see:
vagrant@homestead ~/sites/craft3 $ craft
-bash: craft: command not found
It’s a long story as to why this is the case, but it has to do with how Unix paths work. Typing just ./craft on its own just lists all of the available commands (technically this is the same as ./craft help).
If you see a Permission denied error like this:
vagrant@homestead ~/sites/craft3 $ ./craft
-bash: ./craft: Permission denied
This just means that the craft script doesn’t have executable permissions. You can fix that with the following:
chmod a+x craft
For more information about Unix and Craft permissions, check out the Hardening Craft CMS Permissions article.
So assuming we’ve typed it successfully, we’ll see something like this:
vagrant@homestead ~/sites/craft3 $ ./craft
This is Yii version 2.0.30.
The following commands are available:
- backup Allows you to create a new database backup.
backup/db (default) Creates a new database backup.
- cache Allows you to flush cache.
cache/flush Flushes given cache components.
cache/flush-all Flushes all caches registered in the system.
cache/flush-schema Clears DB schema cache for a given connection component.
cache/index (default) Lists the caches that can be flushed.
- clear-caches Allows you to clear various Craft caches.
clear-caches/all Clear all caches.
clear-caches/asset Asset caches
clear-caches/asset-indexing-data Asset indexing data
clear-caches/compiled-templates Compiled templates
clear-caches/cp-resources Control Panel resources
clear-caches/data Data caches
clear-caches/graphql-caches GraphQL caches
clear-caches/index (default) Lists the caches that can be cleared.
clear-caches/route-map Route Map Cache
clear-caches/temp-files Temp files
clear-caches/template-caches Template caches
clear-caches/transform-indexes Asset transform index
- fixture Allows you to manage test fixtures.
fixture/load (default) Loads the specified fixture data.
fixture/unload Unloads the specified fixtures.
- gc Allows you to manage garbage collection.
gc/run (default) Runs garbage collection.
- graphql Allows you to manage GraphQL schemas.
graphql/dump-schema Dump out a given GraphQL schema to a file.
graphql/print-schema Print out a given GraphQL schema.
- help Provides help information about console commands.
help/index (default) Displays available commands or the detailed information
help/list List all available controllers and actions in machine readable
format.
help/list-action-options List all available options for the $action in machine readable
format.
help/usage Displays usage information for $action.
- index-assets Allows you to re-indexes assets in volumes.
index-assets/all Re-indexes assets across all volumes.
index-assets/one (default) Re-indexes assets from the given volume handle ($startAt = 0).
- install Craft CMS CLI installer.
install/craft (default) Runs the install migration.
install/plugin Installs a plugin.
- mailer Allows for testing mailer settings via the CLI.
mailer/test Allows for the testing of email settings within Craft using one of
the following scenarios:
- migrate Manages Craft and plugin migrations.
migrate/all Runs all pending Craft, plugin, and content migrations.
migrate/create Creates a new migration.
migrate/down Downgrades the application by reverting old migrations.
migrate/fresh Truncates the whole database and starts the migration from the
beginning.
migrate/history Displays the migration history.
migrate/mark Modifies the migration history to the specified version.
migrate/new Displays the un-applied new migrations.
migrate/redo Redoes the last few migrations.
migrate/to Upgrades or downgrades till the specified version.
migrate/up (default) Upgrades the application by applying new migrations.
- project-config Manages the Project Config.
project-config/rebuild Rebuilds the project config.
project-config/sync Syncs the project config.
- queue Manages the queue
queue/exec Executes a job.
queue/info (default) Info about queue status.
queue/listen Listens for new jobs added to the queue and runs them
queue/retry Re-adds a failed job(s) to the queue.
queue/run Runs all jobs in the queue.
- resave Allows you to bulk-saves elements.
resave/assets Re-saves assets.
resave/categories Re-saves categories.
resave/entries Re-saves entries.
resave/matrix-blocks Re-saves Matrix blocks.
resave/tags Re-saves tags.
resave/users Re-saves users.
- restore Restores a database from backup.
restore/db (default) Allows you to restore a database from a backup.
- serve Runs the PHP built-in web server.
serve/index (default) Runs PHP built-in web server.
- setup Craft CMS setup installer.
setup/db Alias for setup/db-creds.
setup/db-creds Stores new DB connection settings to the .env file.
setup/index (default) Sets up all the things.
setup/security-key Generates a new security key and saves it in the .env file.
setup/welcome Called from the post-create-project-cmd Composer hook.
- tests Provides support resources for testing both Craft's own services and
your
tests/setup Sets up a test suite for the current project.
tests/test Don't use this method - it won't actually execute anything.
- update Updates Craft and plugins.
update/composer-install Installs dependencies based on the current composer.json &
composer.lock.
update/info Displays info about available updates.
update/update (default) Updates Craft and/or plugins.
- utils/fix-element-uids Utilities
utils/fix-element-uids/index (default) Ensures all elements UIDs are unique.
To see the help of each command, enter:
craft help <command-name>
Phew, that’s a lot! These are all of the built-in CLI commands as of Craft CMS 3.3.16.1 ; there may be more added later, and plugins can add their own CLI commands too!
We’ll cover what each one does, but the single most important CLI command is:
./craft help <command-name>
If we use the ./craft help command for a top level command, we might see something like this:
vagrant@homestead ~/sites/craft3 $ ./craft help update
DESCRIPTION
Updates Craft and plugins.
SUB-COMMANDS
- update/composer-install Installs dependencies based on the current composer.json & composer.lock.
- update/info Displays info about available updates.
- update/update (default) Updates Craft and/or plugins.
To see the detailed information about individual sub-commands, enter:
craft help <sub-command>
But if we’re a bit more specific with it, and supply the full sub-command such as ./craft help update/composer-install we’ll see a whole lot more help on that specific command, the parameters it takes, etc.:
vagrant@homestead ~/sites/craft3 $ ./craft help update/composer-install
DESCRIPTION
Installs dependencies based on the current composer.json & composer.lock.
USAGE
craft update/composer-install [...options...]
OPTIONS
--appconfig: string
custom application configuration file path.
If not set, default application configuration is used.
--color: boolean, 0 or 1
whether to enable ANSI color in the output.
If not set, ANSI color will only be enabled for terminals that support it.
--help, -h: boolean, 0 or 1
whether to display help information about current command.
--interactive: boolean, 0 or 1 (defaults to 1)
whether to run the command interactively.
I consider the help command to be the most important command, because we can use it to figure out how to use all of the other commands!
Let’s check out the available commands, and what we might use them for.
backup
Yes! As of Craft CMS 3.1.21, you can now back up the database via a console command! Have a look at some of the examples that Brandon noted in the FR:
# create backup in the given folder
./craft backup ./backups
# create backup in working directory with custom filename
./craft backup backup.sql
# create backup in specific location
./craft backup ./backups/backup.sql
# create backup in the storage/backups/ folder
./craft backup
This can be a great addition as a cron job or other automated execution to back up the Craft database!
cache
You’re probably not going to use this command much, if at all. It’s actually coming from Yii2 and deals specifically with the Yii2 data cache, which isn’t used for much of anything in Craft (though many plugins do leverage it).
It has nothing to do with what you probably think of in terms of caching & Craft, which is the {% cache %}
tag. For more on that, check out the The Craft {% cache %}
Tag In-Depth article.
In addition, the clear-caches command (see below) can clear the Yii2 data cache anyway so… nothing to see here, move along.
clear-caches
The clear-caches command is one that I PR’d to the Craft core. It is exactly analogous to the Clear Caches Utility; anything you can clear from the CP, you can now clear from the CLI.
This is especially useful if you want to clear caches when you deploy changes to the website, for example. See the Composer Scripts section below for more on this.
Pro tip: If you see the error Error clearing cache Control Panel resources it’s because for CLI requests, you need to tell Craft where your /cpresources directory is in your general.php file:
'resourceBasePath' => dirname( __DIR__ ) . '/web/cpresources',
You can find a discussion about the above on this GitHub issue.
gc
The gc command is a bit on the obtuse side, so it’s likely only in certain circumstances that you’ll have a use for it. If you use Craft 3.1’s new Soft Deletes feature, and you want to run garbage collection manually or on a fixed time schedule, this is the command for you.
What garbage collection does is it permanently deletes anything that was soft deleted and has expired. Instead of it having a chance of running on any given web request (and thus potentially slowing down the web request), you can control when and how it runs.
help
We’ve talked about this.
index-assets
The index-assets is a PR from Ryan McQuen and does the same job as the Asset Indexes Utility, but it does so via the CLI.
This can be especially handy because asset indexing can take a long time, and will run more reliably via the CLI than web request because it won’t time out or run out of memory during indexing.
install
The install command can be used to install Craft itself (which runs the install migration that sets up the database structure) or to install a plugin. To install a plugin, it needs to already be in your composer.json, but this gives you a way to do it from the CLI, perhaps as part of your boilerplate setup.
If you want to install Craft as part of some larger automated process, you can run it non-interactively, for example:
./craft install \
--interactive=0 \
--email="admin@example.com" \
--username="admin" \
--password="secret" \
--siteName="Craft3" \
--siteUrl="$SITE_URL" \
--language="en"
N.B.: the </kbd> in the above example isn’t unique to the ./craft install command, it’s a generic way to have a multi-line command in Unix shells.
Check out the Setting up a New Craft CMS 3 Project article for more on setting up your own Craft CMS boilerplate setup.
migrate
The migrate command gives you CLI control over your migrations. The most common use-case here is to run migrations as part of your automated build deployment, so you aren’t having to race to the /admin CP to run the migrations when you push updates to Craft CMS or plugins into production.
In this context, a “migration” means a set of database commands that Craft and/or plugins run to change the structure of the database. This is needed from time to time as features are added, or bugs are fixed.
Your website won’t be available to the public until migrations are run, if Craft or plugins have pending migrations.
There’s no way to predict when Craft or plugins will need to do a migration, so it’s best done in an automated way every time you do updates. See the Composer Scripts section below for more on this.
project-config
The project-config/sync is again a command that you’ll most likely run as part of your deployment process, if you’re using Craft CMS 3.1’s new Project Config feature.
Your website won’t be available to the public until Project Config is synced, if you’re using Project Config with Craft 3.1 and changes to the project.yaml have been pushed.
Avoid the pulse-quickening race to the /admin CP to ensure that your project.yaml changes are applied in production when you push them. See the Composer Scripts section below for more on this.
Also new in Craft CMS 3.1.20 is the project-config/rebuild command which will rebuild your project.yaml from the database in the event that something has gotten out of sync.
queue
The queue command allows you to interact with the Craft CMS queue and queue jobs via the CLI. If you’re having issues with stuck queue jobs (which run via web requests, as discussed above), check out the Robust queue job handling in Craft CMS article.
You can then turn off the runQueueAutomatically general.php config setting, and have the queue run in the background via the CLI via ./craft queue/listen
If you don’t want to go to these lengths, the Async Queue plugin from Oliver Stark can give you the same results.
resave
The resave command is the newest Craft CMS CLI command. It once again allows you to run the lengthy and memory intensive “Re-saving Elements” task via the CLI. See this GitHub issue for context.
I think we’re seeing a pattern here with the CLI being useful for lengthy and/or memory intensive operations.
serve
The serve command is a PR from Mark Huot that ensure the Yii2 serve command works with Craft CMS. What does that mean?
It means that with zero local development environment, you can start serving Craft up from a given host/port. Handy for getting things up and running in a jiffy!
setup
The setup command allows you to set up your .env file for environment-specific settings, including database settings, and other “secrets” or things that vary from environment to environment.
This is covered in detail in the Craft Installation instructions, and is a nice interactive way to fill in what’s needed without having to create & edit the .env file directly with an editor.
update
The update command is a way to ease the pain of running Composer via the CP as Pixel & Tonic works on their Update Service. This one deserves mentioning what the sub-commands do explicitly:
- update/update — this does the exact same thing as clicking on the Update button in the CP, but running it via the CLI so you don’t have to worry about Composer timing out or running out of memory
- update/composer-install — this is something you’re use when you deploy Craft CMS, effectively doing the same thing as composer install but for server setups where Composer is not installed.
These commands are useful if you don’t have Composer installed locally or on your server (or just don’t want to deal with Composer), but have run into issues with updating via the CP.
It’s also useful if you want the deployment process to be automated as discussed in the DEPLOYMENT section of the Setting up a New Craft CMS 3 Project article, but again, don’t have Composer available to you.
Composer Scripts
You can run these commands directly as part of your deployment process via a shell script or the like, but you can also leverage Composer.
Composer has a concept of Scripts that can be executed when various things happen. For example, let’s say that you update your Craft CMS site in local development, and then push the composer.lock file to production.
On production, you’d then run the composer install command, and exactly what you installed & tested in local development will then be installed on production.
You might add something like this to the "scripts" section of your composer.json:
"scripts": {
"post-root-package-install": [
"@php -r \"file_exists('.env') || copy('.env.example', '.env');\""
],
"post-create-project-cmd": [
"@php craft setup/welcome"
],
"post-update-cmd": [
"@php craft migrate/all",
"@php craft project-config/sync",
"@php craft clear-caches/all"
],
"post-install-cmd": [
"@php craft migrate/all",
"@php craft project-config/sync",
"@php craft clear-caches/all"
]
}
What this means is that any time composer update or composer install are run, it will run Craft CLI commands to:
- Run all pending migrations
- Sync your project.yaml changes
- Clear all caches
Boom, instant automated deployment. The nice part about this is that it’ll run in local dev, too.
Pro tip: if you do your composer install inside of a buddy.works container or the like, where you don’t want migrations to be run (there may be no database at all), you can use:
composer install --no-scripts
In this way, your composer install will happen, but none of the Composer scripts will be run in an environment where they may not execute properly.
Wrapping up
That’s all she wrote! Hopefully this article has helped demystify the Craft CMS CLI a bit, and given you some ideas of how it can make your development and deployment process better.
Have no fear… the CLI is here! Embrace it where it can help automate things for you, and make your life easier.
Happy deploying!
Further Reading
If you want to be notified about new articles, follow nystudio107 on Twitter.
Copyright ©2020 nystudio107. Designed by nystudio107
Top comments (0)