N98-magerun Tool - Swiss Army Knife for Magento Developers
Dmytro Cheshun Avatar

Most of Magento developers face with the problem of the same operations repetition for many times – that takes some time and slows down the development process. So, it’s a wise idea to simplify and speed up some operations during the work, isn’t it? Fortunately, we have a great CLI tool and it makes Magento developers life easier. It is n98-magerun provided by netz98.

n98-magerun tool is a handy CLI application based on Symfony console package and that gives an ability to perform a variety of operations starting from cache clearing to dummy data generation on your store. It can be also helpful if you want to download and install any Magento release. It is very useful tool, like a swiss army knife, for Magento developers.

n98-magerun contains near 120 available commands for:

  • Development
  • Database
  • Magento system
  • Cache
  • Indexes
  • Configs
  • Locale-config
  • Admin
  • Customer
  • Cms
  • Media
  • Design
  • EAV
  • Extensions
  • Composer
  • Other

Even more, if it is not enough for your work or you want to perform some specific operations, there is a good way to extend the application by creating your own command. But in this article we will talk only about the existing developer kits.

Let’s start working with it. First of all, install the CLI tool. We can do it in two ways:

With wget:

wget http://files.magerun.net/n98-magerun-latest.phar -O n98-magerun.phar

With Curl:

curl -L -o n98-magerun.phar http://files.magerun.net/n98-magerun-latest.phar

Then, execute “.phar” file:

chmod +x ./n98-magerun.phar

Move it to /usr/local/bin if you want to use it widely.

sudo mv ./n98-magerun.phar /usr/local/bin/

Now you can get a list of all available commands by executing:

n98-magerun.phar list

Moreover, there you will also see a short description for each command and their options.

We are going to describe the most commonly used n98-magerun commands which will save your time for development.

Cache

No doubts, the most used operation in Magento is cache clearing. And we have three available commands for this purpose:

  • cache:clean
  • cache:flush
  • cache:dir:flush

The first one cleans the expired cache entries of all available cache types if you do not specify a cache key.

$ n98-magerun.phar cache:clean
Cache config cleaned
Cache layout cleaned
Cache block_html cleaned
Cache translate cleaned
Cache collections cleaned
Cache eav cleaned
Cache config_api cleaned
Cache config_api2 cleaned

$ n98-magerun.phar cache:clean block_html eav
Cache block_html cleaned
Cache eav cleaned

If you would like to remove all the cache entries, use “cache:flush” for this purpose:

$ n98-magerun.phar cache:flush
Cache cleared 

The “cache:dir:flush” command will remove all files within the default “var/cache” directory.

$ n98-magerun.phar cache:dir:f
Flushing cache directory /Users/mitry/Sites/atwix.mg.dev/var/cache
Cache directory flushed

Currently, it is the most effective form to reset default cache storage in Magento. It gives the same effect as you clear the cache from your Magento root directory manually using CLI:

rm -rf var/cache/*

Also, you have the commands to disable/enable cache:

  • cache:disable
  • cache:enable

To list all Magento cache types run “cache:list” command:

$ n98-magerun.phar cache:list

+-------------+---------+
| code        | status  |
+-------------+---------+
| config      | enabled |
| layout      | enabled |
| block_html  | enabled |
| translate   | enabled |
| collections | enabled |
| eav         | enabled |
| config_api  | enabled |
| config_api2 | enabled |
+-------------+---------+

Furthermore, for getting the cache report use the “cache:report” command:

$ n98-magerun.phar -mt cache:report

+--------------------------------------+---------------------+---------------------+-------------+
| ID                                   | EXPIRE              | MTIME               | TAGS        |
+--------------------------------------+---------------------+---------------------+-------------+
| CONFIG_GLOBAL                        | 2286-11-20 17:46:39 | 2016-03-13 11:23:02 | 167_CONFIG  |
| CONFIG_GLOBAL_ADMIN                  | 2286-11-20 17:46:39 | 2016-03-13 11:23:02 | 167_CONFIG  |
| CORE_CACHE_OPTIONS                   | 2286-11-20 17:46:39 | 2016-03-13 11:23:02 | 167_MAGE    |
| CONFIG_GLOBAL_CRONTAB                | 2286-11-20 17:46:39 | 2016-03-13 11:23:02 | 167_CONFIG  |
+--------------------------------------+---------------------+---------------------+-------------+

You can even receive the content of the cache file with IDs using “cache:view” command. By default, it outputs this bunch of text directly into terminal, at first sight, it looks not very informative.

Development

The dev part of n98-magerun is the biggest one. It gives an ability to generate meta data file for PhpStorm auto-compilation. It is useful staff for developers who use PhpStorm IDE.

$ n98-magerun.phar dev:ide:phpstorm:meta

Generated definitions for blocks group
Generated definitions for helpers group
Generated definitions for models group
Generated definitions for resource models group
Generated definitions for resource helpers group
File .phpstorm.meta.php generated

The “.phpstorm.meta.php” will be generated into root directory of your Magento store and you will be able to use it after restarting your IDE.

Phpstorm-auto-completion-for-magento

Also, n98-magerun can simplify and make your workflow with modules more convenient. Create and register any new Magento module just by executing the following command:

dev:module:create [options] [--] <vendorNamespace> <moduleName> [<codePool>] 

For example:

$ n98-magerun.phar dev:module:create --add-all Atwix SampleModule local

Created directory: /Users/mitry/Sites/atwix.mg.dev/app/code/local/Atwix/SampleModule
Created directory: /Users/mitry/Sites/atwix.mg.dev/app/code/local/Atwix/SampleModule/etc
Created directory: /Users/mitry/Sites/atwix.mg.dev/app/code/local/Atwix/SampleModule/Block
Created directory: /Users/mitry/Sites/atwix.mg.dev/app/code/local/Atwix/SampleModule/Helper
Created directory: /Users/mitry/Sites/atwix.mg.dev/app/code/local/Atwix/SampleModule/Model
Created directory: /Users/mitry/Sites/atwix.mg.dev/app/code/local/Atwix/SampleModule/sql/atwix_samplemodule_setup
Created directory: /Users/mitry/Sites/atwix.mg.dev/app/code/local/Atwix/SampleModule/data/atwix_samplemodule_setup
Created file: /Users/mitry/Sites/atwix.mg.dev/app/etc/modules/Atwix_SampleModule.xml (234 bytes)
Created file: /Users/mitry/Sites/atwix.mg.dev/app/code/local/Atwix/SampleModule/etc/config.xml
Created file:/Users/mitry/Sites/atwix.mg.dev/app/code/local/Atwix/SampleModule/etc/readme.md
Created file: /Users/mitry/Sites/atwix.mg.dev/app/code/local/Atwix/SampleModule/etc/composer.json

As you can see, we’ve got “SampleModule” module directory inside of “Atwix” vendor which contains the necessary empty folders and regular config.xml, composer.json, readme.md files in “etc” directory. Moreover, n98-magerun has registered our module by creating “etc/modules/Atwix_SampleModule.xml”.

Here is a content of the generated “config.xml”:

<?xml version="1.0"?>
<config>
    <modules>
        <Atwix_SampleModule>
            <version>1.0.0</version>
        </Atwix_SampleModule>
    </modules>
    <global>
        <blocks>
            <atwix_samplemodule>
                <class>Atwix_SampleModule_Block</class>
            </atwix_samplemodule>
        </blocks>
        <helpers>
            <atwix_samplemodule>
                <class>Atwix_SampleModule_Helper</class>
            </atwix_samplemodule>
        </helpers>
        <models>
            <atwix_samplemodule>
                <class>Atwix_SampleModule_Model</class>
            </atwix_samplemodule>
        </models>
        <resources>
            <atwix_samplemodule_setup>
                <setup>
                    <module>Atwix_SampleModule</module>
                </setup>
            </atwix_samplemodule_setup>
        </resources>
    </global>
</config>

And a content of the generated “etc/modules/Atwix_SampleModule.xml”:

<?xml version="1.0"?>
<config>
    <modules>
        <Atwix_SampleModule>
            <active>true</active>
            <codePool>local</codePool>
            <depends></depends>
        </Atwix_SampleModule>
    </modules>
</config>

If you don’t want to create some files like composer.json or readme.md, it’s quite easy to achieve it by specifying another arguments instead of “–add-all”. To get a list of the available command arguments and usages you can use “-help” or “-h” as an option.

n98-magerun.phar -help dev:module:create

Also, run “n98-magerun.phar dev:module:list” to check the list of the registered modules:

$ n98-magerun.phar dev:module:list

+-----------+---------------------------+----------------+----------+
| codePool  | Name                      | Version        | Status   |
+-----------+---------------------------+----------------+----------+
| core      | Mage_Core                 | 1.6.0.6        | active   |
| core      | Mage_Eav                  | 1.6.0.1        | active   |
| core      | Mage_Page                 | 1.6.0.0        | active   |
| core      | Mage_Install              | 0.7.0          | active   |
| core      | Mage_Admin                | 1.6.1.2        | active   |
...
| core      | Mage_XmlConnect           |                | inactive |
| community | Cm_RedisSession           |                | inactive |
| community | Phoenix_Moneybookers      | 1.6.0.0        | active   |
| local     | Atwix_SampleModule        | 1.0.0          | active   |
+-----------+---------------------------+----------------+----------+

The following commands might be useful for manipulations with modules or getting additional modules information:

  • dev:module:dependencies:on (Show list of modules which given module depends on)
  • dev:module:disable (Disable a module or all modules in codePool)
  • dev:module:enable (Enable a module or all modules in codePool)
  • dev:module:list (List all installed modules)
  • dev:module:rewrite:conflicts (Lists all Magento rewrite conflicts)
  • dev:module:rewrite:list (Lists all Magento rewrites)
  • dev:module:update (Update a Magento module)
  • dev:module:observer:list (Lists all registered observers)

Sometimes, you also need to perform some actions with Magento admin panel system configuration and that might take more time than you expect. For example, if you need to trigger template hints, profiler, merge CSS or JS, etc – you can use one of the following commands instead of the web interface in the admin panel:

  • dev:merge-css (Toggles CSS Merging)
  • dev:merge-js (Toggles JS Merging)
  • dev:profiler (Toggles profiler for debugging)
  • dev:symlinks (Toggle allow symlinks setting)
  • dev:template-hints (Toggles template hints)
  • dev:template-hints-blocks (Toggles template hints block names)
  • dev:translate:admin (Toggle inline translation tool for admin)
  • dev:translate:shop (Toggle inline translation tool for shop)

More commands for dev part you can find by yourself using the “list” parameter mentioned above.

Admin

We already have a good article with tips if there is a need to quickly create a new administrator account or change the password of the existing one. It is a good solution, but we also suggest to try to do it with n98-magerun. For that, execute the “n98-magerun.phar admin:user:change-password” command and then type your username of the existing administrator account and new password.

$ n98-magerun.phar admin:user:change-password

Username:admin
Password:admintest
Password successfully changed

That’s it, now you can login to your admin panel using new password. To create a new administrator with all privileges use “admin:user:create” and fill in your data.

$ n98-magerun.phar admin:user:create

Username:atwixtest
Email:test@atwix.com
Password:atwixpass
Firstname:Test
Lastname:Atwix
The role Development was automatically created.
User atwixtest successfully created

Here n98-magerun creates developer’s role if it doesn’t exist. You may specify any role you want.

admin:user:create [<username>] [<email>] [<password>] [<firstname>] [<lastname>] [<role>]

Proceeding the topic, there is an ability to delete an administrator.

admin:user:delete

To get the list of all admin users, execute:

admin:user:list

The commands below can be also useful for manipulations with an admin part:

  • admin:notifications (Toggles admin notifications)
  • admin:user:change-status (Set active status of an adminhtml user. If no option is set the status will be toggled)

System

n98-magerun gives an ability to check the Magento system by running “n98-magerun.phar sys:check”. It checks and reports the information about:

  • Filesystem
  • Security
  • PHP Extensions
  • MySQL InnoDB Engine
$ n98-magerun.phar sys:check

                            SETTINGS
Secure BaseURL: http://atwix.mg.dev/ of Store: default - OK
Unsecure BaseURL: http://atwix.mg.dev/ of Store: default - OK
Empty cookie Domain (secure) of Store: default - OK
Empty cookie Domain (unsecure) of Store: default - OK

                           FILESYSTEM
Folder media found.
Folder var found.
Folder var/cache found.
Folder var/session found.
File app/etc/local.xml found.
File index.php.sample found.

                              PHP
Required PHP Module simplexml found.
Required PHP Module mcrypt found.
Required PHP Module hash found.
Required PHP Module gd found.
Required PHP Module dom found.
Required PHP Module iconv found.
Required PHP Module curl found.
Required PHP Module soap found.
Required PHP Module pdo found.
Required PHP Module pdo_mysql found.

                            SECURITY
app/etc/local.xml cannot be accessed from outside.


                             MYSQL
MySQL Version 5.7.10 found.
Required MySQL Storage Engine InnoDB found.

When you need to get information about the store, use “sys:info” command:

$ n98-magerun.phar sys:info

  Magento System Information

+---------------------+---------------------------------------------------+
| name                | value                                             |
+---------------------+---------------------------------------------------+
| Version             | 1.9.2.3                                           |
| Edition             | Community                                         |
| Cache Backend       | Zend_Cache_Backend_File                           |
| Cache Directory     | /Users/mitry/Sites/atwix.mg.dev/var/cache         |
| Session             | files                                             |
| Crypt Key           | 97024415fdfe87e082c8c6aa4dfed3dd                  |
| Install Date        | Tue, 15 Mar 2016 10:05:29 +0000                   |
| Vendors (core)      | Mage, Zend                                        |
| Vendors (community) | Cm, Phoenix                                       |
| Attribute Count     | 131                                               |
| Customer Count      | 0                                                 |
| Category Count      | 2                                                 |
| Product Count       | 0                                                 |
+---------------------+---------------------------------------------------+

One more useful thing provided by n98-magerun is that you can run Cron job by providing its code. So, use the below three commands to run Cron job, list all Cron jobs and check the history of the latest executed Cron jobs with their statuses:

  • sys:cron:history
  • sys:cron:list
  • sys:cron:run

Sometimes there is a need to re-run an upgrade or install script during debugging or so. That means you should alter or delete the row in the database manually. Let n98-magerun do it instead of you :) To change a module’s setup resource version just run:

sys:setup:change-version <module> <version> [<setup>]

There is an optional argument to specify setup version to remove. Therefore, you may leave it empty to apply for all setup resources in the module.

$ n98-magerun.phar sys:setup:change-version Atwix_SampleModule 1.0.1 atwix_samplemodule_setup
Successfully updated: "Atwix_SampleModule" - "atwix_samplemodule_setup" to version: "1.0.1"

And to remove module setup resource entry use:

sys:setup:remove <module> [<setup>]

You can also check the versions using “sys:setup:compare-versions”. This command compares modules versions with the saved setup versions in the “core_resource” table and then displays versions mismatch.

$ n98-magerun.phar sys:setup:compare-versions

+--------------------------+----------------+----------------+----------------+--------+
| Setup                    | Module         | DB             | Data           | Status |
+--------------------------+----------------+----------------+----------------+--------+
| admin_setup              | 1.6.1.2        | 1.6.1.2        | 1.6.1.2        | OK     |
| adminnotification_setup  | 1.6.0.0        | 1.6.0.0        | 1.6.0.0        | OK     |
| api2_setup               | 1.0.0.0        | 1.0.0.0        | 1.0.0.0        | OK     |
| api_setup                | 1.6.0.1        | 1.6.0.1        | 1.6.0.1        | OK     |
| atwix_samplemodule_setup | 1.0.1          | 1.0.1          | 1.0.1          | OK     |
...
| widget_setup             | 1.6.0.0        | 1.6.0.0        | 1.6.0.0        | OK     |
| wishlist_setup           | 1.6.0.0        | 1.6.0.0        | 1.6.0.0        | OK     |
+--------------------------+----------------+----------------+----------------+--------+
  
No setup problems were found.

There is one more useful command if you want to enable maintenance mode, for example, when updating your store. For that, you can run all setup scripts from CLI:

$ n98-magerun.phar sys:setup:run
done

The next command runs each new setup script individually in order to increase the transparency of the setup resource system and reduces any chance of PHP failure by creating an invalid database state.

n98-magerun.phar sys:setup:incremental [--stop-on-error]

n98-magerun contains a lot of other commands which you can find and test by yourself – run “n98-magerun.phar list” to get them all.

Magento Installation

n98-magerun gives us an ability to download and install Magento using CLI. And everything that we need is to run “n98-magerun.phar install”, select required release version and provide some required information.

Pay attention that before starting installation you should update n98-magerun to the latest version. To upgrade n98-magerun use “self-update”:

$ n98-magerun.phar self-update

Updating to version 1.97.13.
    Downloading: 100%
Successfully updated n98-magerun

If you do not execute that command, you may not be able to install the latest Magento releases. Also, you may receive an exception like this:

- Installing magento-ce-1.9.1.0 (1.9.1.0)
    Downloading: 100%
internal corruption of phar "/Users/mitry/Sites/atwix.mg.dev/_n98_magerun_download/c6d862a5ba7c8cc9c465dd89963511fe.gz" (__HALT_COMPILER(); not found)

It is because Magento does not offer the downloads anymore – currently all magento-ce-… do not work. And you will receive one more exception message:

- Installing magento-ce-1.9.1.1 (1.9.1.1)
    Downloading: 100%
The checksum verification of the file failed (downloaded from http://www.magentocommerce.com/downloads/assets/1.9.1.1/magento-1.9.1.1.tar.gz)

To avoid this problem you should use any magento-mirror-… packages which are available for all those versions:

$ n98-magerun.phar install

  Magento Installation

[1]  magento-ce-1.9.1.1
[2]  magento-ce-1.9.1.0
[3]  magento-ce-1.9.0.1
[4]  magento-ce-1.8.1.0
[5]  magento-ce-1.8.0.0
[6]  magento-ce-1.7.0.2
[7]  magento-ce-1.6.2.0
[8]  magento-mirror-1.9.2.3
[9]  magento-mirror-1.9.2.2
[10] magento-mirror-1.9.2.1
[11] magento-mirror-1.9.2.0
[12] magento-mirror-1.9.1.1
[13] magento-mirror-1.9.1.0
[14] magento-mirror-1.9.0.1
[15] magento-mirror-1.9.0.0
[16] magento-mirror-1.8.1.0
[17] magento-mirror-1.8.0.0
[18] magento-mirror-1.7.0.2
[19] magento-mirror-1.6.2.0
[20] magento-mirror-1.5.1.0
[21] magento-mirror-1.4.2.0
[22] mageplus-master
Choose a magento version: 8
Enter installation folder: [./magento]
  - Installing magento-mirror-1.9.2.3 (1.9.2.3)
    Downloading: 100%

After Magento package is successfully downloaded, you need to add the database connection information and select if you want to install sample data (by default “yes”).

Please enter the database host [localhost]:
Please enter the database username [root]:
Please enter the database password []: 111
Please enter the database name [magento]: cleanmage
Please enter the database port  [3306]:
Please enter the table prefix []:
Install sample data? [y]:
  - Installing sample-data-1.9.1.0 (1.9.1.0)
    Downloading: 100%

Then fill in the required login and other information, like below is:

Importing /Users/mitry/Sites/atwix.mg.dev/_temp_demo_data/magento_sample_data_for_1.9.1.0.sql with mysql cli client
Please enter the session save: [files]:
Please enter the admin frontname: [admin]:
Please enter the default currency code: [EUR]: USD
Please enter the locale code: [de_DE]: en_US
Please enter the timezone: [Europe/Berlin]: Europe/Kyiv
Please enter the admin username: [admin]: atwix_test
Please enter the admin password: [password123]: atwix_pass
Please enter the admin's firstname: [John]: Dmytro
Please enter the admin's lastname: [Doe]: Cheshun
Please enter the admin's email: [john.doe@example.com]: test@atwix.com
Please enter the base url: http://atwix.mg.dev/

Then it will run regular Magento’s “install.php” script with the specified options:

Start installation process.
/usr/bin/php -f '/Users/mitry/Sites/atwix.mg.dev/install.php' -- --license_agreement_accepted 'yes' --locale 'en_US' --timezone 'Europe/Kyiv' --db_host 'localhost' --db_name 'cleanmage' --db_user 'root' --db_pass '111' --db_prefix '' --url 'http://atwix.mg.dev/' --use_rewrites 'yes' --use_secure 'no' --secure_base_url '' --use_secure_admin 'no' --admin_username 'atwix_test' --admin_lastname 'Cheshun' --admin_firstname 'Dmytro' --admin_email 'test@atwix.com' --admin_password 'atwix_pass' --session_save 'files' --admin_frontname 'admin' --backend_frontname 'admin' --default_currency 'USD' --skip_url_validation 'yes'
Successfully installed Magento
Encryption Key: 97024415fdfe87e082c8c6aa4dfed3dd

As you can see, we have successfully downloaded and installed Magento system with sample data. It usually takes about 5 minutes. No bad, right?

n98-magerun is a very handy application. If you still do not use it – you should definitely try to work with this tool to simplify your work.