Slides

# Terminal basics

## A quick reference for Windows and macOS

A **terminal** is a window where you type commands and read their results.

The **shell** interprets those commands: **PowerShell** on Windows,
usually **zsh** in macOS Terminal.

In this course, the terminal opens your course folder and starts Python apps.
Your **editor** is where you change and save code.

**VS Code** includes an integrated terminal in the editor window.

Reference: <a href="https://learn.microsoft.com/en-us/windows/terminal/">Microsoft: Windows Terminal</a> · <a href="https://support.apple.com/guide/terminal/what-is-terminal-trmld4c92d55/mac">Apple: What is Terminal?</a>

<aside class="notes">
This is a lookup reference, with no exercises or submissions. The commands
assume Windows PowerShell / PowerShell 7 on Windows and zsh on macOS.
An editor's integrated terminal is another terminal window and can use the
same shell. Its current folder can differ from the folder visible in the editor.
Sources checked 28 September 2026.
</aside>

---

# VS Code: opening the terminal

<div class="terminal-columns">
<div>
<ol>
<li>Choose File > Open Folder… and open the extracted course folder containing <code>pyproject.toml</code>.</li>
<li>Choose Terminal > New Terminal.</li>
<li>Click the TERMINAL tab and its prompt before typing a command.</li>
</ol>
<code>pwd</code> shows the current folder. <code>ls</code> should list <code>pyproject.toml</code> and <code>examples</code>.
The same <code>cd</code> and <code>uv</code> commands work here. Opening a Python file alone does not set the terminal's folder.
</div>
<figure>
<a href="assets/terminal-basics/vscode-terminal.png" target="_blank" rel="noopener"><img src="assets/terminal-basics/vscode-terminal.png" alt="VS Code with the integrated terminal below the editor. Red boxes in Microsoft's screenshot mark the TERMINAL tab and powershell shell label." /></a>
<figcaption>The terminal sits below the editor. Microsoft's example folder differs from the course folder. Screenshot © Microsoft, <a href="https://code.visualstudio.com/docs/terminal/getting-started">VS Code documentation</a>, <a href="https://creativecommons.org/licenses/by/3.0/us/">CC BY 3.0 US</a>, unchanged.</figcaption>
</figure>
</div>

Menu alternative: View > Terminal shows the terminal panel. In compact layouts, the menu may be under ….

<aside class="notes">
Use the desktop VS Code application with the local extracted course folder.
New terminals normally start at the workspace root, but settings and restored
sessions can change the location. Each terminal keeps its own working folder.
If the path is wrong, use cd as described later, or right-click the course root
in the Explorer and choose Open in Integrated Terminal.

The Terminal panel runs shell commands. Output displays logs, and Debug Console
is for debugger interaction. Avoid pasting course shell commands into those
panels or directly into a Python source file. The integrated terminal is built
in and requires no terminal extension.

Restricted Mode can block terminal creation. If prompted about workspace trust,
verify that this is the course folder from the instructor before approving it.
Trusting a folder permits features that may execute its code. These instructions
assume a local window, not WSL, SSH, a container, or vscode.dev.

[Sources]

- https://code.visualstudio.com/docs/terminal/getting-started
- https://code.visualstudio.com/docs/terminal/basics
</aside>

---

# VS Code: choosing the shell

<div class="terminal-columns">
<div>
Use the dropdown beside + in the terminal toolbar.
<ul>
<li>Windows: choose PowerShell or Windows PowerShell.</li>
<li>macOS: choose zsh.</li>
</ul>
Selecting a shell opens a new terminal.
To keep that choice, select Select Default Profile, choose the shell, then click +.
The new default applies to new terminals. Existing terminals keep their shell.
</div>
<figure>
<a class="terminal-profile-crop" href="assets/terminal-basics/vscode-profiles.png" target="_blank" rel="noopener"><img src="assets/terminal-basics/vscode-profiles.png" alt="VS Code terminal dropdown with PowerShell and Select Default Profile visible. Microsoft's red boxes mark the plus dropdown and Select Default Profile." /></a>
<figcaption>Windows menu detail. On a Mac, choose zsh. Screenshot © Microsoft, <a href="https://code.visualstudio.com/docs/terminal/profiles">VS Code documentation</a>, <a href="https://creativecommons.org/licenses/by/3.0/us/">CC BY 3.0 US</a>. Click for the full image.</figcaption>
</figure>
</div>

Alternative: View > Command Palette…, then search for Terminal: Select Default Profile.

<aside class="notes">
The available shell names depend on what is installed. VS Code on Windows
normally defaults to PowerShell, while macOS uses the configured system shell.
Windows students following this course use a native PowerShell profile rather
than Command Prompt, Git Bash, or a WSL profile. No WSL installation is needed.
Mac students already using bash can use the shared course commands without
changing their shell. Do not select a new shell merely because a program is
still running: use Control+C in its terminal when you want to stop it.

[Source]

- https://code.visualstudio.com/docs/terminal/profiles
</aside>

---

# VS Code: managing terminals

| What you want to do | Action |
| --- | --- |
| Show the terminal again | **View > Terminal** |
| Hide the panel | Click the panel's **×**. Its running app continues. |
| Stop the running app | Click its terminal, clear any selection, press **Control+C** |
| Open another terminal | Click **+**. Check its folder with `pwd`. |
| Return to an existing terminal | Select its entry in the terminal list |
| End a terminal session | Stop its app, then click that terminal's **trash can** |

Drag the panel's upper border to make more room for commands and output.

**For a course app:** keep its terminal session open while using the browser.
Use another terminal for other commands, or stop the app first.

Source: <a href="https://code.visualstudio.com/docs/terminal/basics#managing-terminals">VS Code: managing terminals</a>

<aside class="notes">
Hiding the panel does not stop the shell or its foreground program. The trash
can kills the terminal instance. Control+C interrupts the foreground program
and normally leaves its shell available for the next command. On macOS, use
the Control key to interrupt. Command+C copies selected text.
With several terminals, select the right session before stopping it. A new
terminal does not replace a busy one. In the tab list's context menu, Rename
can give a session a helpful name such as course app. For these instructions,
the terminal is in the standard bottom panel, not an editor tab.

[Sources]

- https://code.visualstudio.com/docs/terminal/basics#managing-terminals
- https://code.visualstudio.com/docs/terminal/getting-started
</aside>

---

# Windows: opening PowerShell

<div class="terminal-columns">
<div>
<ol>
<li>Open Start, type PowerShell, then open Windows PowerShell or PowerShell.</li>
<li>If you use Windows Terminal, open the dropdown beside + and select a PowerShell profile.</li>
</ol>
PowerShell usually shows a <code>PS …></code> prompt.
The ordinary Open action is enough for the commands in this reference.
</div>
<figure>
<a href="assets/terminal-basics/windows-menu.png" target="_blank" rel="noopener"><img src="assets/terminal-basics/windows-menu.png" alt="Windows Terminal with its profile menu open. Windows PowerShell is the first menu item. The background tab is Command Prompt." /></a>
<figcaption>The Windows PowerShell menu item selects the course shell. Historical screenshot (2019), Ghettoblaster, <a href="https://commons.wikimedia.org/wiki/File:Windows_Terminal_Preview_Screenshot.png">Wikimedia Commons</a>, CC0. Appearance varies by version.</figcaption>
</figure>
</div>

Source: <a href="https://learn.microsoft.com/en-us/windows/terminal/install#open-a-new-tab">Microsoft: opening a shell profile</a>

<aside class="notes">
Windows Terminal is the application, while PowerShell is the shell running
inside it. The screenshot's background shows Command Prompt (cmd), not the
target shell. Use the Windows PowerShell entry in the open dropdown. Windows
PowerShell and PowerShell 7 both support the commands in this deck. No WSL,
administrator window, or PowerShell upgrade is required for this reference.
An editor terminal also works when its selected profile is PowerShell.

[Sources]

- https://learn.microsoft.com/en-us/powershell/scripting/windows-powershell/starting-windows-powershell
- https://learn.microsoft.com/en-us/windows/terminal/install
</aside>

---

# macOS: opening Terminal

1. Open **Spotlight** with **Command+Space**.
2. Type **Terminal**, then open the Terminal app.

You can also open **Finder > Applications > Utilities > Terminal**.
A typical zsh prompt ends with `%`.

<figure class="terminal-wide-figure">
<a href="assets/terminal-basics/macos-terminal.png" target="_blank" rel="noopener"><img src="assets/terminal-basics/macos-terminal.png" alt="Apple's Terminal screenshot: ls after a percent prompt, a list of home folders, then a new prompt and cursor." /></a>
<figcaption>Apple's example: <code>ls</code> lists folders, then the prompt returns. Screenshot © Apple, <a href="https://support.apple.com/guide/terminal/get-started-pht23b129fed/mac">Terminal User Guide</a>. Colours and prompt text vary.</figcaption>
</figure>

Source: <a href="https://support.apple.com/guide/terminal/open-or-quit-terminal-apd5265185d-f365-44cb-8b09-71a064a42125/mac">Apple: opening Terminal</a>

<aside class="notes">
If Spotlight has a different shortcut on the student's keyboard, the Finder
route is the alternative. The usual default shell is zsh. Students already
using bash can use the shared commands without changing their shell.
</aside>

---

# The prompt, command, and result

The **prompt** is the text before the cursor. The shell supplies it.

| Example line | Prompt already on screen | Command you type |
| --- | --- | --- |
| Windows | `PS C:\Users\student>` | `pwd` |
| macOS | `student@Mac ~ %` | `pwd` |

**Copyable command:**

```text
pwd
```

Press **Enter / Return**. The result is your current folder's full path.
When the prompt returns, the shell is ready for another command.

Copy only the command. Leave out example prompts such as `PS …>`, `%`, or `$`.

<aside class="notes">
These are illustrative prompts with fictional account names, not captured
student sessions. pwd reports the current location. PowerShell displays it
under a Path heading, while zsh prints the path itself. Output is produced by
the command executing on the computer. It is distinct from a coding assistant's
prediction of what should happen. Prompt appearance is configurable.

[Sources]

- https://learn.microsoft.com/en-us/powershell/scripting/samples/managing-current-location
- https://support.apple.com/guide/terminal/open-or-quit-terminal-apd5265185d-f365-44cb-8b09-71a064a42125/mac
</aside>

---

# Opening your course folder

Use the **extracted folder containing `pyproject.toml` and `examples`**.

**Windows:** open that folder in File Explorer. Copy its full path from the
address bar, then put it in straight quotes after `cd`:

```powershell
cd 'C:\Users\student\Downloads\aiforlifescience'
```

**macOS:** type `cd` and a space, then drag the course folder from Finder into
Terminal. Review the inserted path and press **Return**. A typed example:

```bash
cd '/Users/student/Downloads/aiforlifescience'
```

Replace the example path with **your own**. Quotes keep a path with spaces together.
`ls` lists the folder's contents, including `pyproject.toml` and `examples`.

Sources: <a href="https://learn.microsoft.com/en-us/powershell/scripting/samples/managing-current-location">Microsoft: changing location</a> · <a href="https://support.apple.com/guide/terminal/drag-items-into-a-terminal-window-trml106/mac">Apple: dragging a folder path</a>

<aside class="notes">
The ZIP must be extracted first. Some downloads contain an extra enclosing
folder. Choose the inner folder that contains pyproject.toml. A file manager
window and a terminal do not automatically share their current folder.
cd changes the shell's working folder. It does not move files.

Use straight quotes, not typographic quotes. A path containing an apostrophe
needs shell-specific quoting. Ask the instructor or coding assistant to explain
the exact path. In PowerShell, cd -LiteralPath '...' handles bracket characters
literally. macOS Terminal inserts escaping when needed for dragged paths, so
leave that escaping in place instead of adding another layer of quotes.
Match filename case exactly, including on case-sensitive Mac filesystems.
</aside>

---

# Folder navigation reference

These commands work in **Windows PowerShell** and **macOS Terminal (zsh)**.

| Command | Meaning |
| --- | --- |
| `pwd` | Show the current folder's full path |
| `ls` | List files and folders here |
| `cd examples` | Enter the `examples` folder, if it is here |
| `cd ..` | Go to the parent folder, one level up |
| `cd ~` | Go to your home folder |
| `cd 'full path'` | Go directly to that folder, using your actual path |

In a path, `.` means **here**, `..` means **parent**, and `~` means **home**.
Keep the space between `cd` and its destination.

Windows paths often use `\`. macOS paths use `/`.
The course's Python script paths with `/` also work on Windows.

Sources: <a href="https://learn.microsoft.com/en-us/powershell/scripting/samples/managing-current-location">Microsoft: locations</a> · <a href="https://support.apple.com/guide/terminal/specify-files-and-folders-apd3cf6fe02-3ec8-48f1-951f-866e52955fc8/mac">Apple: paths</a>

<aside class="notes">
In Windows PowerShell, pwd, ls, and cd are aliases for Get-Location,
Get-ChildItem, and Set-Location. On macOS they use different implementations.
The shared names here do not imply shared command options: for example, Unix
ls options are not PowerShell options. This reference intentionally uses the
common forms. New tabs have their own current folder. Use pwd to identify it.
</aside>

---

# Typing and pasting commands

Use **one complete command at a time**. Read it before running it.

| Action | Windows Terminal | VS Code on Windows | macOS: either app |
| --- | --- | --- | --- |
| Copy selected text | Ctrl+Shift+C | Ctrl+C | Command+C |
| Paste | Ctrl+V | Ctrl+V | Command+V |
| Run the command | Enter | Enter | Return |
| Recall a command | Up arrow | Up arrow | Up arrow |
| Complete a path | Tab | Tab | Tab |
| Cancel input / stop an app | Ctrl+C | Ctrl+C | **Control+C** |

If a paste shortcut differs, use the app's **Paste** menu or right-click action.
Avoid pasting several lines: they may execute immediately.

To correct a typo, use the arrow keys and **Backspace** (Windows) or **Delete** (Mac).
Up arrow recalls text for you to inspect before pressing Enter again.

Sources: <a href="https://learn.microsoft.com/en-us/windows/terminal/customize-settings/actions#clipboard-integration-commands">Windows Terminal</a> · <a href="https://code.visualstudio.com/docs/terminal/basics#copy--paste">VS Code: copy and paste</a> · <a href="https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_line_editing">PowerShell: editing</a> · <a href="https://support.apple.com/guide/terminal/keyboard-shortcuts-trmlshtcts/mac">Apple: shortcuts</a>

<aside class="notes">
Windows Terminal shortcuts can be customized. Ctrl+Shift+V is also a paste
shortcut in Windows Terminal. The older Windows console and editor terminals
can have different bindings. In VS Code on Windows, Ctrl+C copies selected
terminal text, while Ctrl+Shift+C can open an external terminal. Clear a text
selection before Ctrl+C in Windows Terminal or VS Code, because it can copy instead of
interrupting the running program. On macOS, Command+C copies, while Control+C
interrupts. Tab may complete a unique name or offer/cycle through choices.
</aside>

---

# Starting and stopping a course app

After [computer setup](setup.html), enter this in **VS Code's terminal** or your
separate terminal, **from the course folder**:

```text
uv run --group examples python examples/01_pydanticai_chat.py
```

This starts the course's Python app. `uv` may first prepare its dependencies.

- Leave the terminal open while using the app.
- Open the printed address, such as **http://127.0.0.1:7932**, in your browser.
- A running web app keeps the terminal busy. The usual prompt has not returned yet.

To stop it, select its terminal, clear any text selection, and press **Control+C**.
Closing the browser tab alone leaves the app running.

To restart after editing: **save the file, stop the app, then run the command again**.

<aside class="notes">
This is a command reference for the existing examples/01_pydanticai_chat.py,
not an additional activity. Complete the setup guide before starting it,
including the environment file. 127.0.0.1 refers to the student's own computer.
Use the complete uv run command in the terminal. An editor's generic Run Python
File button may use a different interpreter or omit the required dependency group.
The local interface sends submitted questions and conversation context through
PPQ to the model provider. Opening the server does not itself verify a model
answer. The user chooses what to submit.
Control+C sends an interrupt, which most command-line programs handle by
stopping. Wait for the prompt before entering another command in that tab.

[Sources]

- ../examples/01_pydanticai_chat.py
- https://support.apple.com/guide/terminal/execute-commands-and-run-tools-apdb66b5242-0d18-49fc-9c47-a2498b7c91d5/mac
</aside>

---

# Common messages and first checks

| What you see | What to check |
| --- | --- |
| “command not found” / “not recognized” | Check spelling and shell. For `uv`, follow [setup](setup.html), then restart the terminal app or VS Code. |
| “path does not exist” / “no such file” | Use `pwd` and `ls`. Check the actual path, spaces, quotes, and filename case. |
| `>>` or `quote>` after an incomplete command | Press **Control+C**, then enter the complete command with matching quotes. |
| `>>>` | You are inside Python. Enter `exit()` to return to the shell. |
| “permission denied” / “access denied” | Read which file or action failed. Ask the instructor before changing permissions. |

An error message is useful information. Keep the command and the relevant error
together when asking for help.

<aside class="notes">
These are common interpretations, not complete diagnoses. PowerShell's >>
and zsh's quote>/dquote> prompts usually indicate incomplete input. Python's
>>> is a different interpreter, and course shell commands do not belong there.
If uv installation failed on macOS while editing shell files, reopening alone
may not repair the problem. Use the linked macOS uv troubleshooting deck.
Do not default to running as administrator, adding sudo, changing execution
policy, or disabling protections in response to a generic error.

[Sources]

- https://support.apple.com/guide/terminal/execute-commands-and-run-tools-apdb66b5242-0d18-49fc-9c47-a2498b7c91d5/mac
- https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_line_editing
- https://docs.python.org/3/tutorial/appendix.html#interactive-mode
</aside>

---

# Getting help with a command

A coding assistant can explain syntax and suggest a check. Include your
**operating system, shell, command, current folder, and exact error**.

> I use VS Code with PowerShell on Windows [or zsh on macOS]. Here is my command and error,
> with secrets removed. Explain the command, what it changes, and one check
> I can make before trying a fix.

Treat the response as a **suggestion**. Verify the proposed command against the
linked documentation and inspect its actual output.

**Before commands that delete files, install software, change permissions, or
upload data:** review the target and effect, then explicitly approve running them.
Ask the instructor when uncertain.

Remove API keys, passwords, and private details before sharing terminal text or screenshots.

Course references: <a href="setup.html">Computer setup and commands</a> · <a href="macos_uv.html">macOS uv troubleshooting</a> · <a href="coding_assistants.html">Coding assistants</a>

<aside class="notes">
An LLM explanation is model output. The Microsoft and Apple pages are retrieved
documentation. Terminal output comes from the program that actually ran. Keep
these sources distinct when diagnosing a problem. Pasted commands, downloaded
scripts, and assistant-proposed commands cross a code-execution trust boundary.
For a proposed configuration or code edit, save a copy and compare the changed
file before and after. The student reviews the change and checks the result.
Never share .env contents or a full terminal history containing credentials.
</aside>