# The terminal and commands

> **What you will learn**
> What a terminal is and why it survives, how to read one command line, and the
> meaning of `command not found` — where most people get stuck installing.

## What the black window is

A terminal is **a window where you instruct the computer in text.** It does the
same things clicking does. Only the method differs.

| | Screen (GUI) | Terminal (CLI) |
|---|---|---|
| Instruction | click | type |
| Learning | easy | you must know the name |
| **Repeating** | click it again, exactly | **save one line, done** |
| **Recording** | no trace of what you did | **copy it and hand it over** |

**The bottom two rows are why it survives.** Automation and reproducibility —
what you did on screen can only be passed on as "click that thing over there",
while a command pastes and does the same thing again. That is why this manual
gives installation as a single line.

## Opening it

| OS | Program |
|---|---|
| macOS | **Terminal** — search "Terminal" in Spotlight |
| Windows | **PowerShell** — "PowerShell" in the Start menu |
| Linux | Terminal |

You get a blinking line. That is where you type.

```
jinho@macbook ~ %
```

`~` is shorthand for **your home folder** — it says you are currently there.

## The shape of one command

```
claude --version
└──┬─┘ └───┬───┘
command  option
```

```
node scripts/deck-pdf.mjs deck.pdf
└─┬┘ └────────┬─────────┘ └──┬───┘
command   argument      argument
```

**Spaces are the separator.** So a folder name containing a space must be
quoted — the reason the previous chapter preferred hyphens.

```bash
cd "My Documents/work folder"
```

## Five things are enough

Narrowed to what this manual needs:

| Command | What it does |
|---|---|
| `cd <folder>` | move into that folder |
| `ls` (Windows `dir`) | list files here |
| `pwd` | which folder am I in |
| `<command> --version` | is it installed, which version |
| **`Ctrl-C`** | **stop what is running** |

`Ctrl-C` is a key, not a command. It is the exit when something runs and will
not finish — the one you will use most.

> **Pasting may not be `Ctrl-V`.** macOS uses `⌘V`; Windows PowerShell uses
> right-click or `Ctrl-Shift-V`.

## `command not found` — most installation failures

This single line is the most common failure in
[Prerequisites](/guide/ht-prerequisites).

```
zsh: command not found: claude
```

It means "I could not **find** that command". **Not installed and not found are
different.** A terminal does not search everywhere; it looks only in a fixed
list of folders. That list is called **PATH**.

```mermaid
graph TD
  A["you type claude"] --> B["search each folder in PATH"]
  B -->|"found"| C["run it"]
  B -->|"not found"| D["command not found"]
```

Installers usually update PATH. But **a terminal window that was already open
does not know** — it uses the list it read when it opened.

```
✓ open a new terminal window   → fixes it nine times out of ten
✓ still failing? reboot
✗ retyping in the same window  → identical result every time
```

## Spotting a dangerous command

A terminal rarely asks "are you sure?". Before pasting something from the
internet, check these three.

```
□ rm · del        — deletes. Nothing goes to the recycle bin
□ sudo            — runs as administrator
□ curl … | bash   — runs whatever it downloads (check the source is official)
```

**Do not paste a command you do not understand.** Asking an agent "explain what
this command does" first is a good habit.

## Common misconceptions

### "Won't I break the computer with a terminal?"

**Ordinary commands are safe.** The dangerous ones are the three above, and they
are equally dangerous through a graphical tool. The difference is only the
missing confirmation dialog.

### "Do I have to memorise commands?"

**No.** The five above carry you through this manual. The rest you look up when
needed — which is what pages like the
[command reference](/guide/ht-cli) are for.

---

## Check yourself

**1. Does `command not found` mean it is not installed?**

<details>
<summary>Answer</summary>

**Not necessarily.** It means it was not found, and usually the install worked
but PATH has not been re-read. Opening a new terminal is the first move.
</details>

**2. Which key stops a running command?**

<details>
<summary>Answer</summary>

**`Ctrl-C`.**
</details>

**3. Why do folder names with spaces need quotes?**

<details>
<summary>Answer</summary>

**Because the terminal splits the line on spaces.** Unquoted, it reads as two
separate arguments.
</details>

---

Next, what those commands actually run →
[Programs and languages — Python, JavaScript, Node](/guide/it-programs)