# An Illustrated Shell Command Primer

## Introduction

_This guide assumes you have access to the shell on a Linux computer. All the examples use a Raspberry Pi running Raspbian. If you haven't, you should start with [What is this "Linux", anyhow?](../../../what-is-linux) and [What is the Command Line?](../../../../what-is-the-command-line/overview)_

## Choosing Your Own Adventure
This is [Adventure](http://rickadams.org/adventure/), a game almost as old as Unix itself, and much older than Linux:

![](https://cdn-learn.adafruit.com/assets/assets/000/022/076/medium800thumb/raspberry_pi_screencast-2015-01-02-18_11_41.jpg?1448314540)

Like the shell, _Adventure_'s interface is made entirely of text.

You interact with the world of the game by typing commands and reading responses. ENTER BUILDING or [GET LAMP](http://www.getlamp.com/), for example.

## Exploring the Machine
The shell is a lot like that game world, except that instead of a map full of rooms and objects, you navigate a computer's **filesystem** and work with the files it contains.

The filesystem, everything the operating system needs to boot up, run software, save files, take photos, etc. is organized into **directories**. We usually call these "folders" in the Windows and Macintosh worlds, but the concept is the same. A directory is just a special kind of file that can contain other files, including directories.

![](https://cdn-learn.adafruit.com/assets/assets/000/022/077/medium800/raspberry_pi_you_are_here.png?1420311839)

As a user, you have a **home directory**. In the shell, ~ (the [tilde](https://en.wikipedia.org/wiki/Tilde)) is a common shorthand for this. In this case, it points at /home/pi.

Log in to your Pi, acquire a terminal, and verify this:

![](https://cdn-learn.adafruit.com/assets/assets/000/022/078/medium800thumb/raspberry_pi_screencast-2015-01-03-11_00_47.jpg?1448031207)

`pwd` stands for **p** rint **w** orking **d** irectory. Commands in the Unix tradition tend to have short, cryptic names. Some can be easily remembered because they stand for something obvious. Others just have to be committed to memory.

If you have a look around your Pi, you'll find that it contains all sorts of stuff. You just need to know a few more commands. The following pages provide quick introductions to some of the basics.

# An Illustrated Shell Command Primer

## Listing Files: ls

`ls` is used to **l** i **s** t files (note the first letter is the letter L not the number 1!)

Let's try it from our home directory:

![](https://cdn-learn.adafruit.com/assets/assets/000/022/090/medium800thumb/raspberry_pi_screencast-2015-01-03-11_05_51.jpg?1448314553)

Notice that second command and its output?

`ls -a` shows **a** ll the files in a directory, including hidden ones. Why are there hidden files? Because in the Unix world, all directories contain two special sub-directories:

`.` points to the current directory - `/home/pi` is the same as `/home/pi/.`

`..` points to the parent directory, the one that holds the current directory - `/home/pi/..` is really just `/home/`

`ls` normally hides everything starting with a dot, because these don't really convey any extra information to a user.

To complicate matters even further, it's traditional for special configuration files to be stored in `~` and named like `.something` so that they won't show up in a directory listing by default.

Want to see more detail about individual files?

![](https://cdn-learn.adafruit.com/assets/assets/000/022/092/medium800thumb/raspberry_pi_screencast-2015-01-04-00_01_12.jpg?1448314628)

The `-l` option, for a  **l** ong listing, will give you several columns of useful data. For the file called `.bashrc`, you have:

```auto
-rw-r--r--  1 pi   pi    3243 Sep  8 20:23 .bashrc
```

`-rw-r--r--` is a shorthand for the file's type and **mode** or  **permissions**. In this case, the file is a plain old file (not a directory or other special file) and:

- **r** eadable and **w** riteable by its owner
- **r** eadable by its group
- **r** eadable by everyone

The rest of the line, in order:

- `1` is the number of hard links to the file
- `pi`, repeated twice, tells you the  **owner** and  **group** of the file
- `3243` is the number of bytes taken up by the file
- `Sep  8 20:23` is the file's modification time

You don't need to worry too much about this stuff yet - just remember that `-l` gives you more detail.

# An Illustrated Shell Command Primer

## Changing Directories: cd

In order to move around between directories, you use `cd` for  **c** hange  **d** irectory.

You can give cd  **relative paths** , like so:

![](https://cdn-learn.adafruit.com/assets/assets/000/022/094/medium800thumb/raspberry_pi_screencast-2015-01-04-01_00_05.jpg?1448314652)

Remember that ".." is a shortcut for "the directory above this one". 

You can also use an  **absolute path** , like so:

![](https://cdn-learn.adafruit.com/assets/assets/000/022/095/medium800thumb/raspberry_pi_screencast-2015-01-04-01_02_30.jpg?1448314663)

Remember that `/` is the **root** of the filesystem, the top-level directory under which everything else is nested.

The default graphical file manager in Raspbian displays the root directory in a way that's probably familiar from other operating systems:

![](https://cdn-learn.adafruit.com/assets/assets/000/022/096/medium800/raspberry_pi_2015-01-04-210435_647x518_scrot.png?1420405607)

Double-clicking on a folder icon here is equivalent to typing `cd foldername`.  Putting a full path in the location bar at the top, like "/home/pi", is equivalent to typing `cd /home/pi`.

Spend some time looking around the root directory. (There's a lot there, and like the names of commands, it can be pretty cryptic at first. Don't worry if it seems a bit overwhelming; you're just getting the lay of the land.)

Some interesting places:

- `/etc` is full of system-wide configuration files
- `/proc` and `/sys` are full of information about running programs and the kernel
- `/var` contains things like logfiles that the system writes during the course of operation
- `/dev` contains files that map to devices (like drives, network interfaces, and virtual terminals) attached to the system

# An Illustrated Shell Command Primer

## Looking Inside Files: cat, less, head, and tail

I said "look around the root directory", but I left out some important tools for doing that. You already know about listing the contents of directories with `ls`, but what if you want to look at the contents of an individual file?

In a graphical file manager, you might double-click an icon and let your desktop environment decide the appropriate application for opening that kind of file. The shell takes a much different approach. What command you use on a file depends entirely on what you want to accomplish.

# cat
![](https://cdn-learn.adafruit.com/assets/assets/000/022/194/medium800/raspberry_pi_cat_bird.png?1420519822)

`cat` has nothing to do with cats. It's short for **cat** enate, and it dumps the contents of text files.  Cats think about lots of things, but not usually about text files.

For example, here's one that contains basic information about the system's processor:

![](https://cdn-learn.adafruit.com/assets/assets/000/022/097/medium800thumb/raspberry_pi_screencast-2015-01-04-15_07_13.jpg?1448314691)

# less
Sometimes you'll want to look at a really long file, one that takes up more room than you've got in your terminal.

`less` is what's known as a **pager**. It will display one page of a file at a time and let you scroll up and down through the file at your leisure.

`/usr/share/dict/american-english` is a long list of known words in American English. (If that's not available, try `/usr/share/dict/words`, which should point to the dictionary for your Pi's locale.) Try opening it in `less`.

![](https://cdn-learn.adafruit.com/assets/assets/000/022/098/medium800thumb/raspberry_pi_screencast-2015-01-04-15_14_42.jpg?1448314716)

Within `less`, a _ton_ of different keys are available. The basics are easy to remember, but the online help lists all sorts of advanced features.

# head and tail
Sometimes you just want a quick look at the beginning or end of a file. This is useful for getting a sense of the contents of very large files, and for seeing the latest additions to things like logs that routinely have new data appended to them.

![](https://cdn-learn.adafruit.com/assets/assets/000/022/099/medium800thumb/raspberry_pi_screencast-2015-01-04-15_42_14.jpg?1448314758)

If you want to see a different number of lines than the default, you can specify:

![](https://cdn-learn.adafruit.com/assets/assets/000/022/100/medium800thumb/raspberry_pi_screencast-2015-01-04-15_43_44.jpg?1448314773)

# An Illustrated Shell Command Primer

## Attaining Superpowers: sudo

By now, it's possible you've stumbled across a file that seems like it's off-limits to you. That's a little weird, right? It's your computer - why can't you see everything?

It turns out that you can. You just need to assert some authority, which is where `sudo` comes in.

![](https://cdn-learn.adafruit.com/assets/assets/000/022/101/medium800thumb/raspberry_pi_screencast-2015-01-04-16_13_40.jpg?1448314789)

You'll often need to use `sudo` for changing system-wide configuration files, looking at things that have security implications, or installing new software.

We'll address each of those topics in more detail, but for now just remember that the formula is:

```auto
sudo [your command here]
```

If you're using `sudo` for the first time, or for the first time in a few minutes, you'll be prompted for your password.

Info: 

If you're thinking that the access restrictions on some files and actions must exist for a reason, you're right. Raspbian is configured by default to be a pretty wide-open system, with _doing stuff_ taking higher priority than _being really secure about stuff._ Needing to use sudo should always be taken as a sign that you _could_ break something.

On any system, always try to make sure you understand what a command is doing before you run it, or at least be pretty sure you trust the person or website telling you to run it.

# obxcd
One great side effect of this tutorial is that now you will 'get' [Unix nerd joke comics like this one from xkcd.com](http://xkcd.com/149/) (a Mecca of unix nerd joke comments):

![](https://cdn-learn.adafruit.com/assets/assets/000/022/411/medium800/raspberry_pi_sandwich.png?1421177897)

# An Illustrated Shell Command Primer

## Creating Directories and Files: mkdir and touch

## mkdir
Suppose you want to create a directory of your own?

I often keep one called "notes" in my home directory, which in turn contains some text files.

![](https://cdn-learn.adafruit.com/assets/assets/000/022/103/medium800thumb/raspberry_pi_screencast-2015-01-05-10_01_17.jpg?1448314806)

## touch
Suppose we want to add a `hello.txt` to that directory?

![](https://cdn-learn.adafruit.com/assets/assets/000/022/104/medium800thumb/raspberry_pi_screencast-2015-01-05-10_07_00.jpg?1448314826)

`touch` doesn't put anything _inside_ that file. It just creates it.

There's one other thing to know about `touch` : If you run it again a bit later on the same file...

![](https://cdn-learn.adafruit.com/assets/assets/000/022/105/medium800thumb/raspberry_pi_screencast-2015-01-05-10_14_44.jpg?1448314844)

...you'll update the timestamp. This might seem like a trivial thing, but it comes up surprisingly often.

Of course, this is obviously sort of a contrived example. If you're going to have text files, you probably want to put something _in_ them. This is where an editor comes in.

# An Illustrated Shell Command Primer

## Editing Files: nano

`nano` is a little text editor. You can think of it as something like a terminal version of Windows' Notepad.

![](https://cdn-learn.adafruit.com/assets/assets/000/022/102/medium800/raspberry_pi_Screenshot-2015-01-04-16_20_19.png?1420413650)

The great thing about this interface is that it tells you exactly what to do. The bottom two lines of the screen are a cheatsheet for the most commonly used commands.

Just remember that `^` stands for "press the Ctrl key at the same time as". Ctrl-X will quit, Ctrl-O will save a file, etc. It doesn't take long to memorize these, but it's nice not to have to guess.

![](https://cdn-learn.adafruit.com/assets/assets/000/022/107/medium800thumb/raspberry_pi_screencast-2015-01-05-10_25_26.jpg?1448314894)

## Your Friend the Text Editor
Text editors may not seem like the most interesting software, but you'll quickly find that an editor is indispensable for many of the things you want to accomplish in a shell environment.

`nano` is really sort of a baseline editor: It gets the job done, and it's easy on new users. Most modern systems will have it installed by default.

There are substantially more powerful choices that work well in a terminal, like [Emacs](http://www.emacswiki.org/emacs/) and [Vim](http://www.vim.org/), but these come with a steeper learning curve, so for the moment we'll use `nano` in our examples.

# An Illustrated Shell Command Primer

## Moving, Renaming, and Copying Files: mv and cp

# mv
There are two cases in which you're going to need `mv`: One is that a file is in the wrong _directory_. The other is that the file itself has the wrong _name_.

Suppose you've decided that `hello.txt` doesn't really belong in your notes directory.

![](https://cdn-learn.adafruit.com/assets/assets/000/022/108/medium800thumb/raspberry_pi_screencast-2015-01-05-10_38_14.jpg?1448314910)

In this example, we say "move hello.txt up one directory level".

Instead of using `..`, we could have specified `/home/pi`. It's just faster to type a couple of dots. It would have been even faster to type `~`.

Now suppose you've decided that `hello.txt` itself is called the wrong thing, and should be `hello_world.txt` instead.

![](https://cdn-learn.adafruit.com/assets/assets/000/022/109/medium800thumb/raspberry_pi_screencast-2015-01-05-10_44_35.jpg?1448314921)

Remember that a directory is just a special kind of file. `mv` will work to move entire directories just the same as individual files.

Info: 

Always make sure you're not going to overwrite something important when you move a file. There are a couple of good flags to know in order to avoid this:

# cp
In order to duplicate a file, use `cp`:

![](https://cdn-learn.adafruit.com/assets/assets/000/022/111/medium800/raspberry_pi_Screenshot-2015-01-05-11_07_03.png?1420481270)

Trying to copy a directory, however, behaves oddly:

![](https://cdn-learn.adafruit.com/assets/assets/000/022/112/medium800/raspberry_pi_Screenshot-2015-01-05-11_09_01.png?1420481356)

By default, `cp` skips over directories. Why? Well, there's some [good discussion about this](https://unix.stackexchange.com/questions/82485/when-wouldnt-one-want-cp-to-be-recursive) over on Stack Exchange, but the short answer is probably that copying everything in a directory could be a very expensive operation. (Imagine if a directory contained many thousands of files.)

In order to copy a directory, we need to give `cp` the `-r` flag to enable **recursion**. This is part of a broader pattern: In order for many commands to work on entire directories full of files, recursive operations must be specified with a flag, usually `-r` or `-R`.

![](https://cdn-learn.adafruit.com/assets/assets/000/022/114/medium800thumb/raspberry_pi_screencast-2015-01-05-11_19_54.jpg?1448314957)

Info: 

As with `mv`, always make sure you're not going to clobber anything important by copying over it. The `-i`, `-n`, and `-b` flags work here too.

# An Illustrated Shell Command Primer

## Deleting Files and Directories: rm

Info: 

If you want to outright **r** e **m** ove a file, you'll need `rm`. For individual files, just specify the filename(s):

![](https://cdn-learn.adafruit.com/assets/assets/000/022/115/medium800thumb/raspberry_pi_screencast-2015-01-05-11_43_31.jpg?1448314972)

Just like cp, if you want to get a directory, you'll need `-r` for **r** ecursive. `-i` for **i** nteractive also works, and I often use it if I want to be really careful about what I'm doing.

![](https://cdn-learn.adafruit.com/assets/assets/000/022/116/medium800thumb/raspberry_pi_screencast-2015-01-05-11_49_17.jpg?1448314984)

Info: 

You should always be careful with `rm`, and doubly so with _recursive_ rm. It's always a good idea to make sure you know what directory you're in, where the thing you want to delete lives, and that you're _sure_ you want to delete it.

Unlike graphical file managers, `rm` doesn't come with an undo button or a Trash where you can retrieve things. Once a file is gone, you will only be able to get it back at considerable effort, if at all. **Tread lightly!**

# An Illustrated Shell Command Primer

## Disk Space, Memory Use, and CPU Load: du, df, free, and w

# du
It's often necessary to figure out how much space your files are using up, especially on smaller devices like the Raspberry Pi, where storage is frequently limited. This is where `du` (think **d** isk **u** sage, even though your "disk" is probably an SD card) comes in. By default, the output is pretty verbose and hard to read, so I usually use `-h` for **h** uman readable numbers with units and `-s` for a **s** ummary.

![](https://cdn-learn.adafruit.com/assets/assets/000/022/118/medium800thumb/raspberry_pi_screencast-2015-01-05-12_26_11.jpg?1448314991)

You can also specify a path, and without the `-s` it will tell you the size of every file it looks at.

# df
Sometimes it's easier to come at the question by checking how much space is _left_ on a drive.

`df` ( **d** isk **f** ree) provides a quick summary, broken out by device and where that device is attached to:

![](https://cdn-learn.adafruit.com/assets/assets/000/022/117/medium800thumb/raspberry_pi_screencast-2015-01-05-12_21_14.jpg?1448314990)

# free
A resource even more constrained than storage on the Raspberry Pi is RAM. `free` provides a useful quick summary of the state of the computer's memory:

![](https://cdn-learn.adafruit.com/assets/assets/000/022/119/medium800thumb/raspberry_pi_screencast-2015-01-05-12_27_58.jpg?1448314998)

Again, `-h` gets you **h** uman-readable numbers with units. Here's a [good breakdown of how to read those numbers](http://www.linfo.org/free.html).

# w
It can also be useful to know **w** ho's logged in, the system's uptime, and CPU load average for the last 1, 5, and 15 minutes. That's the grab bag of info supplied by `w`:

![](https://cdn-learn.adafruit.com/assets/assets/000/022/120/medium800thumb/raspberry_pi_screencast-2015-01-05-12_28_48.jpg?1448314999)

You can also get just that first bit by running `uptime`.

### 

That's kind of a tricky question. The first thing you need to know is that higher numbers mean more load. The second thing is that it matters how many processors you have - mentally divide the number you see by the number of processors, and that's the number you should worry about.

What's a number you should worry about? Well, it depends. Here's a good [detailed explanation](http://blog.scoutapp.com/articles/2009/07/31/understanding-load-averages).

# An Illustrated Shell Command Primer

## Further Reading

![](https://cdn-learn.adafruit.com/assets/assets/000/023/233/medium800/raspberry_pi_pngn_primer_sitting.png?1424105508)

The shell's part of a whole culture with its own history and literature. There's no one right way to learn about something like that, any more than there's one right way to approach human culture in general. Here're some suggestions for other things that might be helpful.

Perhaps unsurprisingly, Wikipedia has a lot of good information about command-line utilities. You could profitably start just about anywhere near their [Unix](https://en.wikipedia.org/wiki/Unix) entry. For example, this [list of Unix commands](https://en.wikipedia.org/wiki/List_of_Unix_commands).

There's a [Unix & Linux Stack Exchange](https://unix.stackexchange.com/).

[Earlier](../../../../what-is-the-command-line/ancient-history) I mentioned _[The Unix Programming Environment](http://www.amazon.com/Programming-Environment-Prentice-Hall-Software-Series/dp/013937681X)_, by Brian Kernighan and Rob Pike. It's that rare technical book that's worth your time more than 30 years after its first publication.

My edition of _[Linux in a Nutshell](http://www.amazon.com/Linux-Nutshell-Ellen-Siever/dp/0596154488)_, by Ellen Siever et al., is a decade or more out of date, but I still flip through it from time to time and learn something new.

And last, I've been working for a while now on _[userland: a book about the command line for humans](https://p1k3.com/userland-book/)_. If this guide just isn't doing the trick, _userland_'s more literary and detailed take on the subject might be worth checking out. (On the downside, it doesn't have nearly as many animated GIFs.)

That's just about it for now, but stay tuned - from here we'll be tackling more advanced shell usage:

- [An Illustrated Guide to Shell Magic: Standard I/O & Redirection](../../../../basic-shell-magic/overview), which covers features like pipes, redirection, and standard IO that allow us to stitch little commands together - the true power of the shell.
- Aliases, wildcards, loops, and other techniques for typing less and accomplishing more.
- Writing scripts to solve larger problems.
- What it means when we say that "everything is a file".
- System administration tasks like upgrading and installing software via `apt` and other package managers.
- Data munging for fun and profit.


## Featured Products

### Raspberry Pi 1 Model B+ Starter Pack - Includes a Raspberry Pi 1

[Raspberry Pi 1 Model B+ Starter Pack - Includes a Raspberry Pi 1](https://www.adafruit.com/product/2125)
You're going to work hard with your Raspberry Pi B+.  You're going to have to solder, code, and Linux your Maker heart out.  That's why we've tried to make it as easy as possible to start - by combining the Raspberry Pi B+ with what we think are the best...

No Longer Stocked
[Buy Now](https://www.adafruit.com/product/2125)
[Related Guides to the Product](https://learn.adafruit.com/products/2125/guides)

## Related Guides

- [What is the Command Line?](https://learn.adafruit.com/what-is-the-command-line.md)
- [Local LLMs on Raspberry Pi](https://learn.adafruit.com/local-llms-on-raspberry-pi.md)
- [Control an LED With Your Voice using Watson and Raspberry Pi](https://learn.adafruit.com/tjbot-control-an-led-with-your-voice-watson-on-raspberry-pi.md)
- [Teddy Ruxpin Rebuild](https://learn.adafruit.com/teddy-ruxpin-rebuild.md)
- [Pico W PiCowBell Case](https://learn.adafruit.com/pico-w-picowbell-case.md)
- [Adafruit CH334F Mini USB Hub Breakouts](https://learn.adafruit.com/adafruit-ch334f-mini-4-port-usb-hub-breakout.md)
- [Severance Portable Macrodata Refinement Terminal](https://learn.adafruit.com/portable-macrodata-refinement-terminal.md)
- [Python Virtual Environment Usage on Raspberry Pi](https://learn.adafruit.com/python-virtual-environment-usage-on-raspberry-pi.md)
- [Use Docker to Compile Linux for ESP32-S3](https://learn.adafruit.com/docker-esp32-s3-linux.md)
- [Adafruit Mini PiTFT - Color TFT Add-ons for Raspberry Pi](https://learn.adafruit.com/adafruit-mini-pitft-135x240-color-tft-add-on-for-raspberry-pi.md)
- [Adafruit 1.3" Color TFT Bonnet for Raspberry Pi](https://learn.adafruit.com/adafruit-1-3-color-tft-bonnet-for-raspberry-pi.md)
- [CircuitPython Libraries on Linux and ODROID C2](https://learn.adafruit.com/circuitpython-libaries-linux-odroid-c2.md)
- [Raspberry Pi Rotary Encoder Animated Gif Player](https://learn.adafruit.com/python-rotary-animated-gif-player-two-different-ways.md)
- [NFC Raspberry Pi Media Player](https://learn.adafruit.com/nfc-raspberry-pi-media-player.md)
- [Install bluez on the Raspberry Pi](https://learn.adafruit.com/install-bluez-on-the-raspberry-pi.md)