GPM Command

Since the release of version 0.9.3, Grav includes a GPM (Grav Package Manager) which allows you to install, update, uninstall and list all the themes and plugins available on the Grav repository, as well as upgrade Grav itself to the latest version.

Like the Grav CLI, the GPM is a command-line tool which requires the user to run commands via a command-line interface, such as Terminal in MacOS. UNIX style commands are not natively available in Windows cmd. Installing the msysgit package on a Windows machine adds Git and Git BASH, which is an alternative command prompt that makes UNIX commands available.

To get started with GPM, you can run the following command to receive a list of all presently available commands:

bin/gpm list

To receive help for a specific command, you can add help to the line before the command:

bin/gpm help install

PHP CGI-FCGI Information

To determine if your server is running cgi-fcgi on the command line, type the following:

php -v
PHP 5.5.17 (cgi-fcgi) (built: Sep 19 2014 09:49:55)
Copyright (c) 1997-2014 The PHP Group
Zend Engine v2.5.0, Copyright (c) 1998-2014 Zend Technologies
    with the ionCube PHP Loader v4.6.1, Copyright (c) 2002-2014, by ionCube Ltd.

If you see a reference to (cgi-fcgi) you will need to prefix all bin/gpm commands with php-cli. Alternatively, you can set up an alias in your shell with something like: alias php="php-cli" which will ensure the CLI version of PHP runs from the command line.

How Does it Work?

GPM downloads the repository metadata from GetGrav.org. The repository contains all the details about the packages available and GPM is also capable of determining whether any of these packages are already installed and if they need updating.

The repository itself gets cached locally, on the Grav instance machine running the command, for 24 hours. Any further request after the cache has been generated will not contact the GetGrav.org server, but rather serve from the locally-stored repository. This approach guarantees a much quicker response.

Most of the commands (listed below) come with the option --force (-f) which allows the forcing a re-fetch of the repository. This could be extremely useful in the event an update is known to be out there and the user doesn't want to wait a full 24-hour cycle before the cache gets cleared.

Commands

Below, we have broken down all of the commands available for GPM. To run a command, launch your favorite terminal app and from within the root of your Grav instance, you can type bin/gpm <command>.

Index

The index command shows a list of all the available resources in the Grav repository, organized by themes and plugins.

Each row displays the name, slug, version and whether it's installed already or not.

In this view, you can also quickly determine if there is a new version of any of the resources you have already installed.

For instance, if we had a very old version of Antimatter (v1.1.1), but the latest version was v1.1.3, it will appear in the index as seen below.

Info

The info command displays the details of the desired package, such as description, author, homepage, etc.

Install

The install command does exactly what it states. It installs a resource from the repository to your current Grav instance with a simple command.

The command will also detect if a resource is already installed, or if it is symbolically linked, and prompts you on what to do.

You can also install multiple resources at once by separating the slugs with a space.

Update

The update command shows a list of updatable resources and works similarly to install.

Alternatively, you can limit the updates to specific resources only.

Uninstall

The uninstall command removes an installed theme or plugin and clears the cache. Because Grav is purely filesystem, uninstalling a theme or a plugin means deleting the folder physically.

The command will also detect if a resource is symbolically linked, and prompts you on what to do.

You can also uninstall multiple resources at once by separating the slugs with a space.

Self-upgrade

The self-upgrade (or selfupgrade) allows you to update Grav to the latest available version. If no upgrade is needed, a message will tell you so, noting also which version you are currently running and when the release was published.

It is strongly advised to always do a backup before performing a self-upgrade (see Creating a Backup in the CLI section).

Important Developer Information

Blueprints

With the introduction of GPM, we now have strict rules about valid blueprints. Whether it's a theme or a plugin you are developing, you should always ensure blueprints are formatted properly.

A blueprint can serve several different purposes, including defining your resource identity. Please refer to the Blueprints for more detailed documentation about what blueprints are and how they should be compiled.

Releases

Grav repository refreshes every hour and automatically detects when there are new releases, this implies that as a developer you followed our Contributing requirements.

On your end all you have to do is ensure you have updated the blueprints with the new version, and that you tagged and released the new version. The Grav repository will do the rest for you and as soon as your release is picked up, it will be available to everyone via Grav website or through GPM.

Add your resource to the repository

advanced/grav-development#themeplugin-release-process Follow the instructions in the Theme/Plugin Release Process section.

To add your new plugin/theme to the Grav repository, please open a Grav Issue on GitHub. You can also use this precompiled link. Make sure you update the body to the proper user/repository.

More details about what the plugin/theme does are welcome and can be placed in the Issue.

Also please be aware that before adding a repository, the Grav team will inspect your plugin/theme ensuring that it fits the Grav standards. The team may also respond with requests for additional information, suggest minor improvements, etc. prior to closing the issue and adding the plugin/theme.