Hello Shell

Legend

Parts of this exercise are annotated with the following icons:

• A task you MUST perform to complete the exercise
• Optional step that you may perform to make sure that everything is working correctly, or to set up additional tools that are not required but can help you
• Advanced tips on how to go further (or challenges!)
• The end of the exercise
• The architecture of the software you ran or deployed during this exercise
• Troubleshooting tips: how to fix common problems you might encounter

Install WSL (Windows only)

Skip this step if you are on macOS or Linux.

Windows users: this exercise, and everything that follows in this course, happens in the Windows Subsystem for Linux (WSL), not in PowerShell or the Windows command prompt. If you have not installed it yet, do so before you start: installing the WSL step by step walks through it.

Set your editor

You will edit a file during the hunt, and later in the course other programs will open a text editor for you without asking. Tell them to use nano, so that none of them opens Vim when you did not choose it.

Add the line to your shell’s configuration file:

$> echo 'export EDITOR=nano' >> ~/.bashrc  # in the WSL
$> echo 'export EDITOR=nano' >> ~/.zshrc   # on macOS

Then close your terminal and open a new one.

Prepare the hunt

The rule of the hunt. The goal of this exercise is to learn to use the command line, so do everything in your terminal: the Terminal on macOS, the WSL on Windows. Do not look at the files of the hunt in the Finder, the Windows file explorer or a graphical editor.

Do not remember a command? Look it up in the Command Line cheatsheet, in the sidebar. It is there for that, and the hunt will send you there too.

Run this command:

$> curl -fsSL https://tinyurl.com/archidep-hunt | bash

curl downloads a script. The pipe (|) sends that script to bash, which runs it. The script creates a directory named treasure-hunt in your home directory, and everything the hunt needs inside it.

Tip

Want to start over? Run the same curl command again. It asks before it deletes your hunt.

Go on the hunt

Go where the script put the hunt, and read start.txt:

$> cd ~/treasure-hunt
$> cat start.txt

Everything you need is on the island from now on: each place tells you what to do and where to go next, and each one also has a hint in a hidden file if you are stuck (cat .hint). You will not need this page again until you have the treasure.

On the way, you will:

• Move around the file system and see what is in it (cd, ls, pwd).
• Read files, short and long (cat, less).
• Create, copy, move, rename and delete files and directories (mkdir, touch, cp, mv, rm).
• Edit a file with nano (or Vim). You will do this a lot on your server later in the course.
• Run programs, stop one that does not stop by itself, and make one executable.
• Look for what ls does not show you (ls -a, find).

Take the treasure home

This last step is for when the chest is open and the treasure is in your bag. Not there yet? Go back to the island: the hunt sends you here when it is done with you.

The treasure is a program in your bag. You can run it with its path:

$> ~/treasure-hunt/bag/treasure

But you cannot run it with its name only, like ls or cd:

$> treasure
command not found: treasure

Your shell looks for commands in the directories listed in your PATH, and your bag is not one of them. Take your bag everywhere: add ~/treasure-hunt/bag to your PATH, as explained in the PATH variable of “Command Line”.

• Look at your PATH with echo $PATH.

• Open your shell’s configuration file with nano: ~/.bashrc in the WSL, ~/.zshrc on macOS.

• Add this line at the end of the file, then save and quit:

  export PATH="$HOME/treasure-hunt/bag:$PATH"
  

• Close your terminal and open a new one.

• Run treasure, from any directory.

What have I done?

You interacted with your computer through nothing but text. The island you explored is an ordinary directory in your home directory, and the Finder or the Windows file explorer would have shown you the same files all along: same computer, same file system, a different way of reaching it. Instead of seeing things and clicking them, you named them and told a program what to do with them.

The rule of the hunt is lifted, so go and see that for yourself: open the island in your graphical interface. If your terminal is still open, the quickest way is to ask for it there:

$> cd ~/treasure-hunt
$> open .            # on macOS
$> explorer.exe .    # in the WSL

There is the beach, there is the old temple with the space in its name, and there is your bag with the treasure in it. Nothing you did happened in a separate command line land that only exists inside the terminal: you were moving these very icons around the whole time. Drag a file somewhere with the mouse, then run ls in your terminal, and you will see the same change from both sides.

On the way to the treasure, you:

• Moved around directories with relative and absolute paths.
• Read files with cat and less.
• Found hidden files and (possibly) a file lost deep in a tree.
• Moved, renamed, copied, created, edited and deleted files.
• Ran programs, stopped one, and made another one executable.
• Added a directory to your PATH so that the shell finds the treasure from anywhere.

Underneath those commands, you learned that your file system is a tree, and that a path is an address in it: . is where you stand, .. is one step up, ~ is your home and / is the root that everything hangs from. Every file on your computer has such an address, and once you can write it, you can reach anything from anywhere. You also saw that the tree makes no distinction between kinds of things: a clue, a key, a configuration file and a program were all just files, and the same handful of commands worked on all of them.

You learned that a command is itself one of those files. ls and cat are not magic words the terminal knows: they are programs, sitting in a directory, that your shell found by looking through your PATH. That is why putting your bag in your PATH turned treasure into a command exactly like them. There is no privileged list of real commands that you are not allowed to add to.

Two things also work differently here than in a graphical interface, and both are worth carrying with you:

• There is no trash bin and no undo: rm deletes a file forever, which is why you double-check each name before pressing Enter.
• Settings often live in plain text: you opened the drawbridge by editing drawbridge.conf in nano or vim, which is how a Unix system is typically configured.

That last point is why this chapter comes first. The server you will be given later in the course has no Finder, no windows, no GUI at all: a text-based command line is the only way in, and everything you just did on the island is what you will be doing on it when you get there.

Keep your treasure

The hunt is over, but do not delete it yet: keep ~/treasure-hunt and the line you added to your PATH. Your adventure continues in Hello SSH, and your treasure will be useful there. That exercise ends by explaining how to clean up everything.

Make your own hunt

You played someone else’s hunt. Now build one, and make a friend play it.

Create a directory with three places in it. Put a clue in each one, each clue pointing at the next place, and the treasure in the last place.

Then play your own hunt by hand, the way you played the one on the island: see what’s there (ls), read the first clue (cat), follow it to the next place (cd), and go on until you dig up the treasure.

Automate it

You have to type those four commands, in that order, every single time you want to see your hunt played, and so does everyone you show it to. Write that walk down once instead, in a file the computer runs for you.

That is what a script is: anything you can type in your terminal, you can put in a file and have the machine do for you, the same way every time, as often as you want, on any machine. The treasure hunt you played on the island is itself such a script: it typed several hundred mkdir, echo and chmod commands so that you did not have to.

• Write a script that goes through the places in order and shows each clue with cat. Pause two seconds between clues for dramatic effect with sleep 2.
• Make the script executable (“Make a file executable”), then run it (“Run a program”).

Tip

The Shell Scripting Cheatsheet has everything you need here — the #!/bin/bash line every script starts with, how to define a function, and how to run the finished script.

Troubleshooting

Here’s a few tips about some problems you may encounter during this exercise.

The command that prepares the hunt fails

If the curl command that prepares the hunt fails with an error about its options, or says that bash is not found, you probably typed it in PowerShell or in the Windows command prompt. Open the WSL (Ubuntu) and run it there.

My shell’s configuration file lost its content

If you typed > instead of >> when you added a line to ~/.bashrc or ~/.zshrc, the file now contains only that line. > replaces the content of a file, while >> adds to its end (see the echo command in “Command Line”).

In the WSL, get Ubuntu’s default ~/.bashrc back, then add your line again with >>:

$> cp /etc/skel/.bashrc ~/

On macOS, there is no default ~/.zshrc to get back: the file does not exist until something creates it. Add back the lines you know were in it. Or delete it and open a new terminal: macOS will create a new ~/.zshrc with the default content.

My terminal seems frozen

A program is probably still running. Read what is on the screen: it may tell you how to stop it. Otherwise:

• Ctrl-C stops most programs (see Stop a running command in the cheatsheet).
• Press q to quit less or a scrolling help page.
• Press Ctrl-X to quit nano.
• Press Esc, type :q! and press Enter to quit Vim (see Help, Vim opened and I can’t get out in “Command Line”).

treasure is still not found after I changed my PATH

Check these, in this order:

• Did you open a new terminal? Your shell only reads its configuration file when it starts.
• Did you add the directory ~/treasure-hunt/bag, and not the file ~/treasure-hunt/bag/treasure? The PATH is a list of directories.
• Did you edit the right file? It is ~/.bashrc in the WSL and ~/.zshrc on macOS. echo $0 tells you which shell you are using.
• Is your line exactly the one on this page? Write $HOME, not ~: Zsh does not replace a ~ inside quotes with your home directory.

In a new terminal, echo $PATH shows whether your bag is in your PATH.

Every command is now command not found

If even ls or nano is now command not found, the line you added probably does not end with :$PATH. Your PATH then contains only your bag, and your shell does not find any other command.

Run nano with its full path to open your configuration file:

$> /usr/bin/nano ~/.bashrc  # in the WSL
$> /usr/bin/nano ~/.zshrc   # on macOS

Fix the line so that it is exactly the one on this page, save, and open a new terminal.