Introduction to n98-magerun

This article is part of a longer series covering the n98-magerun power tool

I’m starting a new series here on Magento Quickies covering the n98-magerun command line tool. This is a nifty utility that automates a lot of the day-to-day drudgery of working with a Magento system, and is a nice compliment to Commerce Bug’s diagnostic information.

This series is appropriate for both newbies and experienced developers. If you can run ls, you can follow along.

Installing

There’s a few different ways to install n98-magerun. You can clone the github repository, or download the latest magerun.phar directly

https://raw.github.com/netz98/n98-magerun/master/n98-magerun.phar

You can download this phar file via a web browser, or with the curl or wget command line programs.

wget https://raw.github.com/netz98/n98-magerun/master/n98-magerun.phar
curl -o n98-magerun.phar https://raw.github.com/netz98/n98-magerun/master/n98-magerun.phar

After downloading the file, you can test it by running the following command

$ php n98-magerun.phar

This should result in help output similar to the following.

$ php n98-magerun.phar

     ___ ___
 _ _/ _ ( _ )___ _ __  __ _ __ _ ___ _ _ _  _ _ _
| ' _, / _ ___| '  / _` / _` / -_) '_| || | ' 
|_||_/_/___/   |_|_|___,___, ___|_|  _,_|_||_|
                           |___/
n98-magerun version 1.61.3 by netz98 new media GmbH

Usage:
  [options] command [arguments]

Options:
  --help           -h Display this help message.
  --quiet          -q Do not output any message.
  --verbose        -v Increase verbosity of messages.
  --version        -V Display this application version.
  --ansi              Force ANSI output.
  --no-ansi           Disable ANSI output.
  --no-interaction -n Do not ask any interactive question.

Available commands:
  help                             Displays help for a command
  install                          Install magento
  list                             Lists commands
  mysql-client                     Opens mysql client by database config from local.xml
  open-browser                     Open current project in browser (experimental)
  self-update                      Updates n98-magerun.phar to the latest version.
  selfupdate                       Updates n98-magerun.phar to the latest version.
  shell                            Runs n98-magerun as shell
  uninstall                        Uninstall magento (drops database and empties current folder

[... commands ommited ...]

extension
  extension:download               Download magento-connect package
  extension:install                Install magento-connect package
  extension:list                   List magento connection extensions
  extension:search                 List magento connection extensions
  extension:upgrade                Upgrade magento-connect package

[... commands ommited ...]

This help output lists all the commands available via n98-magerun. You can get detailed help for a specific command by passing in help as the first paramater to the CLI program. For example if you wanted help on the extension:list command, just enter

$ php n98-magerun.phar help extension:list

and you’ll see something like the following

Usage:
 extension:list [search]

Aliases: extension:search
Arguments:
 search                Search string

Options:
 --help (-h)           Display this help message.
 --quiet (-q)          Do not output any message.
 --verbose (-v)        Increase verbosity of messages.
 --version (-V)        Display this application version.
 --ansi                Force ANSI output.
 --no-ansi             Disable ANSI output.
 --no-interaction (-n) Do not ask any interactive question.

While terse, these help entries do give you a list of arguments for the command. For example, reading the above we see that extension:list has a search argument, which will allow us to list specific Magento extensions. We’ll come back to this in a bit, but first we need to learn how to run commands

Running n98-magerun Commands

Let’s try running the extension:list command from above. To run a command, just pass it in as the first argument. The command is the entire colon separated string.

If you try running

$ php n98-magerun.phar extension:list

you’ll probably see the following output.

  [RuntimeException]                    
  Magento folder could not be detected  

extension:list [search]

Drat! An error. The first thing you need to know about running n98-magerun commands is they need to be run from within your magento folder.

Give the following a try instead (substituting your Magento path)

$ cd /path/to/magento
$ php /path/to/n98-magerun.phar extension:list

This time you should see a huge list of extensions output to your screen.

+-----------------------------------------+--------------------+--------+
| Package                                 | Version            | Stabi  |
+-----------------------------------------+--------------------+--------+
| Lib_Google_Checkout                     | 1.5.0.0            | stable |
| ... almost 4,000 extensions snipped ... |                    |        |
| Contacts_Captcha                        | 0.1.0              | stable |
+-----------------------------------------+--------------------+--------+    

Success! You’ve successfully run your first n98-magerun command.

You don’t need to be at the top of your Magento directory hierarchy to run commands. The n98-magerun program will correctly detect your Magento folder no matter how deep you are — even if the folders are symlinks. For example, all of the following commands will work

$ cd /path/to/magento/app/code/community
$ php /path/to/n98-magerun.phar extension:list

$ cd /path/to/magento/app/design/frontend
$ php /path/to/n98-magerun.phar extension:list

Command Arguments

Remember the help text we saw earlier?

Usage:
 extension:list [search]

Aliases: extension:search
Arguments:
 search                Search string

This indicates that n98-magerun has a single search parameter, which means running the command with Mage as the second parameter

$ php /path/to/n98-magerun.phar extension:list Mage

will filter out any extension that doesn’t have Mage in the name. In other words, it will search for extensions with Mage in the name.

It’s often necessary to make intuitive leaps like this when working with command line tools. Interpreting phrases like Search string may seem frustrating at first, but every command line tool has its own logic and culture. After a few days of use you’ll start to get the feel for these sorts of intuitive jumps, and there’s always the Magento Stack Exchange in the meantime.

Less Verbose

We’ll finish today with a quick lesson on general shell scripting. The command we’ve been using to run n98-magerun

$ php /path/to/n98-magerun.phar extension:list Mage

is a little verbose. Let’s take some steps to make running n98-magerun as simple as running any other command line program.

The first step is getting rid of the leading php. It’s possible to run PHP scripts as plain old *nix* executables by making them executable. Use the chmod command to do this.

$ chmod +x /path/to/n98-magerun.phar

Here we’re using the chmod command to “add” (the +) the executable bit (the x) to the file /path/to/n98-magerun.phar. For those new to *nix, this tells the system its allowed to run this file as a program.

After doing the above, we’ll be able to run n98-magerun with the following

$ /path/to/n98-magerun.phar extension:list

For experienced PHP folks, this works because the first line of the phar archive is #!/usr/bin/env php.

Removing the Path

There’s still the problem of needing to traverse the full /path/to/n98-magerun.phar. You have a few options here — we’re going to talk about *nix aliasing, but for the more experienced folks there’s no reason you can’t copy the phar into a location your $PATH can see, add the /path/to/n98-magerun.phar directory to your $PATH, or use a symlink.

The alias command allows you to assign a shorter, simpler command string to run a larger, more complex program. If you run the following from your shell.

$ alias n98-magerun="/path/to/n98-magerun.phar"

you’ll then be able to run the /path/to/n98-magerun.phar command via the shorter n98-magerun alias.

$ n98-magerun

This will only last as long as the current terminal window is open. To have this alias run automatically whenever you open a terminal window, you’ll need to add a line to the your shell’s startup profile. This is probably the file .bash_profile, and if it isn’t it means you’re running a shell other than bash. Google around for instructions for your particular shell.

Here’s a quick one liner to add this alias to your bash profile

$ printf "nalias n98-magerun="/path/to/n98-magerun.phar"n" >> ~/.bash_profile

This command automatically appends the alias command to the .bash_profile file in your home directory. You could also open this file with your favorite text editor and add the command yourself.

With this alias in place, you should be able to open a terminal window and run the n98-magerun command with a single word

$ n98-magerun
$ n98-magerun extension:list

Wrap Up

That’s your introduction to n98-magerun! In our next few articles we’ll start covering n98-magerun’s more useful commands, as well as what that weird phar file really is.