Commands, arguments, flags, and reading an error

Two failures, and telling them apart will save you an evening more than once.

$ pythn3 hello.py
zsh: command not found: pythn3

$ python3 hello.py
/opt/homebrew/bin/python3: can't open file '/Users/you/hello.py': [Errno 2] No such file or directory

The $ is the prompt, and the line beside it is what somebody typed. Everything below it is the machine answering.

Two things about how those are printed, because your screen will differ and I would rather you knew why. The word at the very front is whoever is talking. A current Mac says zsh:, because that is its shell; Linux and Git Bash usually say bash:, and some messages put the words in a different order. And the long paths are real. Python prints the full address of the Python that ran and the full address of the file it went looking for, so yours will be longer than mine and will have your name in it. That second path is the most useful thing on the line, and in a moment you will see why.

Both say something could not be found. They're completely different problems with completely different fixes, and by the end of this lesson you'll tell them apart in about a second.

The first one is the shell saying: I looked for a program with that name, and there isn't one. The second is a program that started perfectly well and then couldn't find the file you handed it.

Most people scroll past both, and that habit costs more than any other at a terminal. It isn't laziness. Error text looks like a wall rather than a sentence, so the eye slides off it. So this lesson teaches the grammar first, because once you can see the parts of a command, the parts of an error message stop being a wall.

A command is a sentence

Every command you type has the same shape.

program   flags        arguments
python3   --version
ls        -l           Documents
rm        -r           drafts

The program comes first, always. It's the name of a thing on your machine that can be run.

Flags change how the program behaves. By convention they start with a dash: one dash for a single letter, -l, or two dashes for a word, --version. People also call them options or switches.

Arguments say what the program should act on. Usually they are file or directory names, which means they are the addresses you learned in lesson 2, which means they are relative to where you are standing unless they start with a /.

That's the whole grammar, and ls -l Documents reads as: run ls, in its long form, on Documents.

Once you can see that, a command you've never met stops being an incantation. You may not know what it does, and you can still say which word is the program, which parts are changing the behaviour, and which are the things being acted on. That's enough to look the rest up, and enough to notice when somebody has handed you something you shouldn't run.

Ask the program about itself

There are two ways to find out what a command does, and you should learn the escape from the second one before you learn the way in.

--help usually prints a short summary straight to the screen and hands your prompt back. On Linux and in Git Bash, ls --help does exactly that.

On a Mac most of these commands are an older family that has no --help at all, and what you get is this:

$ ls --help
ls: unrecognized option `--help'
usage: ls [-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,] [--color=when] [-D format] [file ...]

That looks like a failure and it is half an answer: the second line is the command's own summary of its grammar, which is the thing you wanted. Do not reach for -h instead. On a Mac -h is a real flag on many commands and it means something else entirely; ls -h quietly prints a directory listing, and a reader who tries it concludes that is what help looks like.

man, short for manual, opens the full documentation. Run man ls.

Press q to get out. Do that now, before you read another word about it.

I put that before the description on purpose, and the reason is on the record. Software Carpentry's instructor notes say that learners "can sometimes get trapped within command-line text editors such as Vim, Emacs, or Nano", and that the only escape they find is closing the terminal and opening a new one, which means finding their way back to where they were.¹ That is about editors. Extending the same caution to the manual is my judgement rather than theirs, and it is an easy call, because the manual opens in a program of its own with no visible way out either.

So: q quits the manual. If you are ever somewhere you can't get out of and q does nothing, try Control and C, which interrupts whatever is running, and if you find yourself in an editor called nano the way out is Control and X.

The manual is dense and it isn't written for beginners. Read it anyway, in one specific way: go to the section headed NAME for a one-line description, then SYNOPSIS for the grammar of the command, then skim DESCRIPTION for the flag you are trying to understand. Ignore the rest until you need it.

Making, copying, moving, and the one with no undo

There are five to know here, and the last one needs care.

mkdir reports makes a directory called reports, where you are standing.

touch notes.txt makes an empty file, or, if the file exists, leaves it alone and updates the time on it.

cp notes.txt notes-backup.txt copies. The first argument is the original, the second is the copy, and that order holds for the next one too.

mv notes.txt archive/ moves. It's also how you rename: mv notes.txt minutes.txt gives the same file a new name, in the same directory, which is exactly the rename from lesson 2 typed rather than clicked.

rm notes.txt removes.

What actually happens when you press return

Now the mechanism. It's short, and it explains both of the error messages at the top of this lesson.

When you press return, the shell does this:

1. It splits your line into words at the spaces.
2. It takes the first word and treats it as the name of a program.
3. It goes looking for a program with that name, in a list of directories it keeps for the purpose.
4. If it finds one, it starts it, and hands it all the remaining words.
5. The program then does whatever it does with those words, which usually means treating them as file names and going looking.

Two of those steps can fail, and they fail with different messages.

Step 3 failing is command not found. The shell looked in its list and there was no such program. The fault is the name, or the program genuinely isn't installed. Nothing ran.

Step 5 failing is No such file or directory. The program was found, it started, and then it couldn't find something it was told to act on. The fault is the argument, and far more often than not that means you're standing somewhere other than where you think, which is lesson 4's whole subject.

Look again at step 1, because it has a consequence people meet before they meet the explanation. The shell splits at spaces, so a directory called My Practice arrives as two separate words, and the command gets My and Practice rather than one name. The tell is unmistakable once you know it: the error names only the first word.

$ cd My Practice
bash: cd: My: No such file or directory

Nothing is wrong with the folder. Put quotes round the name, cd "My Practice", or type cd My and press Tab and let completion write it for you, which is the better habit and is lesson 4's point arriving again.

You can see step 3 for yourself. which python3 prints the full address of the program the shell would run, and echo $PATH prints the list of directories it searched, separated by colons. On the machine I am writing this on, which python3 answers /opt/homebrew/bin/python3, and that directory is the first entry in the list.⁵ Yours will differ, and the shape won't.

Running something you wrote

Here is the exercise the whole terminal half of this course has been building towards. Do it properly, because the Foval Core's Python course in Term 6 opens by assuming you can.

You will need a plain text editor, and lesson 3 is where you found out which of your programs actually produces plain text. If you skipped that, go back: a file that's nearly plain text will cost you half an hour here and you'll blame the wrong thing.

First, check whether you have Python at all.

python3 --version

Two outcomes, and both are worked, because both are useful.

If it answers with a version number, something like Python 3.14.7, you have it. That's the whole of the check.

If it says command not found, you don't have it, or the shell can't see it. That isn't a failure of this lesson; it's the lesson working. You have just read a message and diagnosed it correctly. If you want to fix it, python.org has installers, and lesson 9 is about how to decide whether to trust a download before you run it.

Now the rest.

mkdir practice
cd practice

Now the part that trips people up, and it is not the typing. Your editor's Save box needs to be pointed at practice, and the surest way is to take the address from the terminal rather than hunt for the folder. Run pwd and copy what it prints. On macOS, in the Save box press Command, Shift and G and paste it in. On Windows and most Linux file dialogs, click into the address or file-name field and paste it there.

Then type exactly this one line and save it as hello.py:

print("Hello from a file")

Then, with the terminal still standing in practice:

python3 hello.py

It prints Hello from a file.

Break it three ways on purpose

Anyone can run a thing that works. The skill is what you do when it doesn't, and the cheapest way to build it is to cause each failure yourself, while you already know the answer.

Break the location. Type cd .. so you are one level above practice, then run python3 hello.py again.

/opt/homebrew/bin/python3: can't open file '/Users/you/hello.py': [Errno 2] No such file or directory

Yours will read differently at both ends and mean the same thing.⁵ What holds everywhere is the words can't open file and No such file or directory, and the address inside the quotation marks, which is where Python actually went looking. Compare it with what pwd prints and the fault is in front of you: Python looked one level too high, because that is where you were standing.

Read it as a sentence: Python started, and Python couldn't find the file. The program is fine, the file is fine, the standing point is wrong. cd practice and it works again.

Break the program name. Go back into practice and type pythn3 hello.py.

zsh: command not found: pythn3

On Linux or in Git Bash the same failure reads bash: pythn3: command not found, with the words in a different order and a different name at the front. That name is the shell saying who is speaking, and it is itself half the diagnosis: this message came from the shell and not from a program, because no program ever started.

Different failure, different message, different fix. The file was never even looked at.

Break the program. Edit hello.py and change print to prnt, then run it again.

Traceback (most recent call last):
  File "/Users/you/practice/hello.py", line 1, in <module>
    prnt("Hello from a file")
    ^^^^
NameError: name 'prnt' is not defined. Did you mean: 'print'?

This is the third category. It looks the most frightening and it's the friendliest of the three, because Python found the file, read it, ran it, stopped on something it didn't understand, and then told you four things: the file by its full address, the line number, the exact text, and a guess at what you meant. The full address is worth more than it looks. The first time you have two copies of something, it is how you find out which one just ran.

Notice the shape of the diagnosis, because it generalises to errors this course will never show you:

What people get wrong

"An error means I broke something." Almost every error at a terminal is the computer telling you precisely what it couldn't do. It's the most cooperative thing on the screen. Nothing on your machine is damaged by a command that failed to run.

"The error is the last line, so the rest is noise." The last line is usually the category of the problem, and the lines above it are where it happened. In the traceback above, the last line names the mistake and the line above it tells you which file and which line number to open. Read the whole thing, bottom to top, and stop when you've got both.

"If the command is right, it will work anywhere." Lesson 4's subject, and the first of the three breakages above. Any argument that isn't an absolute path is relative to where you're standing.

"rm puts things in the bin." It doesn't, which is why the callout above exists and why the practice below has you delete something you made on purpose rather than finding out on something you care about.

"Flags are optional decoration." rm -r is a different instruction from rm. So is cp -r. A flag can change what a command is willing to do, not just how it reports.

"Reading the manual is for when you're stuck." It's for the thirty seconds before you run something a stranger sent you. NAME and SYNOPSIS take about that long, and they are the cheapest safety check in this lesson.

Practice

Connections

Lesson 4 gave you a standing point. This lesson gave you the grammar of the thing you type from it, and the two of them together are what make an error message readable rather than alarming.

Lesson 6 is where the terminal finally does something the mouse cannot. You'll send the output of one command into another and answer a question about your own files that no amount of clicking would have answered.

Lesson 9 comes back to python3 --version from a different direction: when it says the command isn't found and you go off to install something, what exactly are you trusting, and how do you check?

If you take Python Basics in Term 6, everything in its first lesson about opening a terminal, saving a file and reading the error assumes this lesson and the last one. The eighth step of the first exercise above, the page with the three messages on it, is the thing worth keeping.

Go deeper

• Software Carpentry, The Unix Shell, free and CC BY licensed. Episode 3 is "Working With Files and Directories", which is the same ground as the making-and-moving section above; episode 4 is "Pipes and Filters", which is where lesson 6 goes. This course has read the homepage, episode 2 and the instructor notes, and lists the others by title, so take the recommendation as a pointer rather than a review.
• MIT, The Missing Semester of Your CS Education, lecture 1. Where this lesson's scope comes from: the command grammar, man, --help, which, and the idea of teaching by having the learner hit an error and work out why.² It moves quickly and assumes you can program.
• The Linux Command Line, free to read online. A full-length book on the shell. This course has not worked through it and makes no claim about any chapter of it; it is here so you know a thorough version exists.

Sources

1. Software Carpentry, "The Unix Shell" (shell-novice), swcarpentry.github.io/shell-novice, CC BY 4.0. The instructor notes read in full. Supplies the record of learners getting trapped inside manual pagers and command-line editors, which is why the way out of man is given before the way in.
2. MIT, "The Missing Semester of Your CS Education", missing.csail.mit.edu, CC BY-NC-SA. Homepage and the 2020 edition's lecture 1 notes read in full. Supplies the command grammar of program, flags and arguments, the man and --help pair, which and $PATH, and the exercise design of having a learner hit an error deliberately and work out why.
3. Foval Learning Institute, Python Basics lesson 1, "Your first program, and your first error", read in full. Supplies the criterion this lesson's main exercise is measured against: a learner who finishes it can make a folder, save hello.py into it, cd there, run python3 hello.py, and, when it fails, say from the message alone whether the fault is the location, the program name, or the program.
4. Python Software Foundation, "Using Python on Windows", docs.python.org/3/using/windows.html. Read 18 September 2026. Supplies the whole of the Windows callout: that python is the recommended command with py alongside it; the sentence quoted there about the python3 command, which is verbatim; that adding Python to PATH is offered as optional at install time; and the documented fix for an app execution alias, which is to open Manage app execution aliases from the Start menu and check the Python entries. The winpty point is not from this source and is marked in the lesson as reported community practice rather than documentation.
5. Checked on the machine this lesson was written on, macOS 26 with zsh and a Homebrew Python, September 2026. python3 --version answered Python 3.14.7. which python3 answered /opt/homebrew/bin/python3, the first entry in $PATH. Running the file from the directory above produced a line beginning with the full path of the Python that ran and quoting the full path it looked for, ending [Errno 2] No such file or directory; the samples above are shortened at both ends so they fit the page, and the shape is exact. pythn3 hello.py produced zsh: command not found: pythn3 under zsh and bash: pythn3: command not found under bash. prnt("Hello from a file") produced the traceback shown, with the file named by its absolute path and Python's own "Did you mean" suggestion. cd My Practice produced bash: cd: My: No such file or directory. rm on a directory produced rm: d: is a directory. which cd answered cd: shell built-in command. ls --help produced ls: unrecognized option followed by a usage line, and ls -h produced an ordinary directory listing.