Installing and Running n98-magerun
There’s a few different ways to install n98-magerun. While you can clone the github repository, it may be easier to download the latest magerun.phar directly
1 https://raw.github.com/netz98/n98-magerun/master/n98-magerun.phar
You can download this phar file via a web browser, or, if you’re already CLI savvy, with programs like curl or wget.
1 wget https://raw.github.com/netz98/n98-magerun/master/n98-magerun.phar
2 curl -o n98-magerun.phar https://raw.github.com/netz98/n98-magerun/master/n98-ma\
3 gerun.phar
After downloading the file, you can test it by running the following command from a terminal window
1 $ php n98-magerun.phar
This should result in help output similar to the following.
1 $ php n98-magerun.phar
2
3 ___ ___
4 _ _/ _ ( _ )___ _ __ __ _ __ _ ___ _ _ _ _ _ _
5 | ' \_, / _ \___| ' \/ _` / _` / -_) '_| || | ' \
6 |_||_/_/\___/ |_|_|_\__,_\__, \___|_| \_,_|_||_|
7 |___/
8 n98-magerun version 1.61.3 by netz98 new media GmbH
9
10 Usage:
11 [options] command [arguments]
12
13 Options:
14 --help -h Display this help message.
15 --quiet -q Do not output any message.
16 --verbose -v Increase verbosity of messages.
17 --version -V Display this application version.
18 --ansi Force ANSI output.
19 --no-ansi Disable ANSI output.
20 --no-interaction -n Do not ask any interactive question.
21
22 Available commands:
23 help Displays help for a command
24 install Install magento
25 list Lists commands
26 mysql-client Opens mysql client by database config from lo\
27 cal.xml
28 open-browser Open current project in browser (experimental)
29 self-update Updates n98-magerun.phar to the latest versio\
30 n.
31 selfupdate Updates n98-magerun.phar to the latest versio\
32 n.
33 shell Runs n98-magerun as shell
34 uninstall Uninstall magento (drops database and empties\
35 current folder
36
37 [... commands ommited ...]
38
39 extension
40 extension:download Download magento-connect package
41 extension:install Install magento-connect package
42 extension:list List magento connection extensions
43 extension:search List magento connection extensions
44 extension:upgrade Upgrade magento-connect package
45
46 [... commands ommited ...]
This help output lists all the commands available to an n98-magerun user. You can retrieve detailed help for a specific command by passing in help as the first parameter to the CLI program. For example if you wanted help on the extension:list command, just enter
1 $ php n98-magerun.phar help extension:list
and you’ll see something like the following
1 Usage:
2 extension:list [search]
3
4 Aliases: extension:search
5 Arguments:
6 search Search string
7
8 Options:
9 --help (-h) Display this help message.
10 --quiet (-q) Do not output any message.
11 --verbose (-v) Increase verbosity of messages.
12 --version (-V) Display this application version.
13 --ansi Force ANSI output.
14 --no-ansi Disable ANSI output.
15 --no-interaction (-n) Do not ask any interactive question.
While seemingly terse, the value in these help entries is the 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
1 $ php n98-magerun.phar extension:list
you’ll probably see the following output.
1 [RuntimeException]
2 Magento folder could not be detected
3
4 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)
1 $ cd /path/to/magento
2 $ php /path/to/n98-magerun.phar extension:list
This time you should see a huge list of extensions output to your screen.
1 +-----------------------------------------+--------------------+--------+
2 | Package | Version | Stabi |
3 +-----------------------------------------+--------------------+--------+
4 | Lib_Google_Checkout | 1.5.0.0 | stable |
5 | ... almost 4,000 extensions snipped ... | | |
6 | Contacts_Captcha | 0.1.0 | stable |
7 +-----------------------------------------+--------------------+--------+
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
1 $ cd /path/to/magento/app/code/community
2 $ php /path/to/n98-magerun.phar extension:list
3
4 $ cd /path/to/magento/app/design/frontend
5 $ php /path/to/n98-magerun.phar extension:list
Command Arguments
Remember the help text we saw earlier?
1 Usage:
2 extension:list [search]
3
4 Aliases: extension:search
5 Arguments:
6 search Search string
This tells us n98-magerun has a single search parameter, which means running the command with Mage as the second parameter
1 $ 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 communities like the Magento Stack Exchange to help out if you get stuck.
Unix Shell Scripting 101
The command we’ve been using to run n98-magerun
1 $ php /path/to/n98-magerun.phar extension:list Mage
is a little verbose. Fortunately, the unix command line gives us the power to simplify command strings. Let’s take some steps to make our n98-magerun command strings as simple as 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.
1 $ 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 it’s allowed to run (or “execute”) this file as a program.
After doing the above, we’ll be able to run n98-magerun with the following
1 $ /path/to/n98-magerun.phar extension:list
For experienced PHP folks who are interested, this works because the first line of the phar archive is #!/usr/bin/env php.
Removing the Path
Next up for our simplification is the problem of needing to traverse the full /path/to/n98-magerun.phar. There’s 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.
1 $ 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.
1 $ 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
1 $ 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. The above command is actually two commands. The first is a simple printf statement. If you execute this by itself, you’ll see the following
1 $ printf "\nalias n98-magerun=\"/path/to/n98-magerun.phar\"\n"
2
3 alias n98-magerun="/path/to/n98-magerun.phar"
That is, the command string alias n98-magerun="/path/to/n98-magerun.phar" is output the screen. “The screen” is sometimes refereed to as “standard output”. Next, and most importantly, we use unix redirection (>>) to append the output of the command to the file ~/.bash_profile.
1 [command] >> ~/.bash_profile
The ~ character is a shortcut that means “the current user’s home directory”. This sort of redirection is incredibly powerful, and while you won’t need to use it with n98-magerun, mastering it is a valuable skill to pickup if you’ll be using the unix command line.
If that’s all a little fancy, you could also open ~/.bash_profile with your favorite text editor and add the alias command yourself to the end.
1 $ vim ~/.bash_profile
Regardless of how it got there, with this alias in place you should be able to open a terminal window and run the n98-magerun command with a single word
1 $ n98-magerun
2 $ n98-magerun extension:list
We’re now ready to move on and start exploring the abundance of commands available to us with n98-magerun.