feat: add Module 02 — CLI Tools curriculum

Five projects covering Click and Typer for building command-line tools:
01 Click Basics, 02 Multi-Command CLI, 03 Interactive Prompts,
04 File Processor CLI (with Rich progress bars), 05 Typer Migration.
Each project includes project.py with extensive comments, README with
alter/break/fix/explain exercises, and a notes.md template.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: travisjneuman

projects/modules/02-cli-tools/01-click-basics/README.md

@@ -0,0 +1,92 @@
+# Module 02 / Project 01 -- Click Basics
+
+Home: [README](../../../../README.md)
+
+## Focus
+
+- `@click.command()` decorator to define a CLI entry point
+- `@click.option()` for optional flags like `--shout`
+- `@click.argument()` for required positional values
+- Automatic `--help` text generation
+
+## Why this project exists
+
+Most Python scripts start with `if __name__ == "__main__"` and a handful of `input()` calls. That works for throwaway code, but real tools need named options, help text, and predictable argument parsing. Click handles all of that with decorators you stack on top of a plain function. This project shows you how.
+
+## Run
+
+```bash
+cd projects/modules/02-cli-tools/01-click-basics
+
+# Basic greeting
+python project.py World
+
+# Greeting with the --shout flag
+python project.py World --shout
+
+# View auto-generated help
+python project.py --help
+
+# Greeting with a custom greeting word
+python project.py World --greeting Howdy
+```
+
+## Expected output
+
+```text
+$ python project.py World
+Hello, World!
+
+$ python project.py World --shout
+HELLO, WORLD!
+
+$ python project.py World --greeting Howdy
+Howdy, World!
+
+$ python project.py --help
+Usage: project.py [OPTIONS] NAME
+
+  Greet someone by name. A small first step into Click.
+
+Options:
+  --greeting TEXT  Word to use for the greeting.  [default: Hello]
+  --shout          Uppercase the entire output.
+  --help           Show this message and exit.
+```
+
+## Alter it
+
+1. Add a `--repeat` option (integer, default 1) that prints the greeting N times.
+2. Add a `--farewell` flag that prints a goodbye message after the greeting.
+3. Change the default greeting word from "Hello" to something else and confirm `--help` reflects the change.
+
+## Break it
+
+1. Remove the `@click.argument("name")` decorator and run the script. What error do you get?
+2. Change `is_flag=True` on `--shout` to `type=int`. Try running with `--shout`. What happens?
+3. Pass two positional arguments instead of one. How does Click respond?
+
+## Fix it
+
+1. Restore the missing decorator and confirm the greeting works again.
+2. Revert `--shout` back to a boolean flag and verify `--shout` toggles uppercasing.
+3. Read the Click docs on `nargs` and decide whether your tool should accept multiple names.
+
+## Explain it
+
+1. What does `@click.command()` do that a bare function does not?
+2. How does Click generate the `--help` text -- where does it pull the description from?
+3. What is the difference between `@click.option()` and `@click.argument()` in terms of required vs optional?
+4. Why does Click use decorators instead of requiring you to subclass something?
+
+## Mastery check
+
+You can move on when you can:
+- write a Click command from scratch without copying this file,
+- explain what `is_flag=True` does vs a typed option,
+- add a new option, re-run `--help`, and confirm it appears,
+- break and recover in one session.
+
+## Next
+
+Continue to [02 - Multi-Command CLI](../02-multi-command-cli/).

projects/modules/02-cli-tools/01-click-basics/notes.md

@@ -0,0 +1,10 @@
+# Notes -- Module 02 / Project 01 -- Click Basics
+
+## What I learned
+
+
+## What confused me
+
+
+## What I want to explore next
+

projects/modules/02-cli-tools/01-click-basics/project.py

@@ -0,0 +1,58 @@
+"""Module 02 / Project 01 -- Click Basics.
+
+This script builds a simple greeting CLI to demonstrate the three
+core Click decorators: @click.command(), @click.option(), and
+@click.argument().
+
+Run it with:
+    python project.py World
+    python project.py World --shout
+    python project.py --help
+"""
+
+# click is a third-party library for building command-line interfaces.
+# Install it with: pip install click
+import click
+
+
+# @click.command() turns this function into a CLI entry point.
+# Click reads the docstring and uses it as the help description.
+@click.command()
+# @click.argument() defines a required positional value.
+# "name" becomes the first thing the user types after the script name.
+@click.argument("name")
+# @click.option() defines an optional flag.
+# --greeting has a default value so the user can skip it.
+@click.option(
+    "--greeting",
+    default="Hello",
+    help="Word to use for the greeting.",
+    show_default=True,
+)
+# is_flag=True means --shout is a boolean toggle: present = True, absent = False.
+@click.option(
+    "--shout",
+    is_flag=True,
+    help="Uppercase the entire output.",
+)
+def greet(name, greeting, shout):
+    """Greet someone by name. A small first step into Click."""
+
+    # Build the message from the greeting word and the name argument.
+    message = f"{greeting}, {name}!"
+
+    # If the user passed --shout, convert everything to uppercase.
+    if shout:
+        message = message.upper()
+
+    # click.echo() is Click's version of print().
+    # It handles encoding issues on Windows and plays nicely with pipes.
+    click.echo(message)
+
+
+# Standard Python entry-point guard.
+# When you run "python project.py", Python sets __name__ to "__main__".
+# Without this guard, importing the file would execute the CLI immediately.
+if __name__ == "__main__":
+    # Call the decorated function. Click takes over argument parsing here.
+    greet()

projects/modules/02-cli-tools/02-multi-command-cli/README.md

@@ -0,0 +1,92 @@
+# Module 02 / Project 02 -- Multi-Command CLI
+
+Home: [README](../../../../README.md)
+
+## Focus
+
+- `@click.group()` to bundle related commands under one tool
+- Defining subcommands with `@group.command()`
+- Sharing options across subcommands
+- Building a practical file utility
+
+## Why this project exists
+
+Real CLI tools rarely do just one thing. Git has `commit`, `push`, `log`. Docker has `build`, `run`, `stop`. Click's group system lets you organize multiple commands under a single entry point so users type `tool info myfile.txt` instead of remembering five separate scripts. This project shows you how to build that structure.
+
+## Run
+
+```bash
+cd projects/modules/02-cli-tools/02-multi-command-cli
+
+# Show top-level help
+python project.py --help
+
+# Show file info (size, modified date)
+python project.py info project.py
+
+# Count lines, words, and characters
+python project.py count project.py
+
+# Show the first 5 lines (default)
+python project.py head project.py
+
+# Show the first 10 lines
+python project.py head project.py --lines 10
+```
+
+## Expected output
+
+```text
+$ python project.py info project.py
+File:     project.py
+Size:     2,341 bytes
+Modified: 2026-02-24 14:30:00
+
+$ python project.py count project.py
+Lines: 87
+Words: 312
+Chars: 2,341
+
+$ python project.py head project.py --lines 3
+"""Module 02 / Project 02 -- Multi-Command CLI.
+...first 3 lines of file...
+```
+
+(Exact numbers will vary depending on the file.)
+
+## Alter it
+
+1. Add a `tail` subcommand that shows the last N lines of a file.
+2. Add a `--bytes` flag to the `info` subcommand that displays size in KB or MB when the file is large enough.
+3. Add a `search` subcommand that takes a `--pattern` option and prints matching lines with line numbers.
+
+## Break it
+
+1. Remove the `@cli.command()` decorator from `info`. Run `python project.py info project.py`. What happens?
+2. Pass a filename that does not exist to `count`. How does the tool respond?
+3. Change `@click.group()` to `@click.command()` and try running a subcommand. What error appears?
+
+## Fix it
+
+1. Restore the decorator and confirm `info` appears in `--help` again.
+2. Add a file-existence check before opening the file, and print a clear error message if the file is missing.
+3. Revert to `@click.group()` and verify all subcommands work.
+
+## Explain it
+
+1. What is the relationship between `@click.group()` and `@cli.command()`?
+2. How does Click know which subcommand the user wants to run?
+3. Why is `click.Path(exists=True)` useful and how does it differ from checking `os.path.exists()` yourself?
+4. If two subcommands need the same option, what are your options for avoiding duplication?
+
+## Mastery check
+
+You can move on when you can:
+- create a group with at least three subcommands from memory,
+- explain how Click dispatches to the correct subcommand,
+- add a new subcommand without breaking existing ones,
+- handle missing-file errors gracefully.
+
+## Next
+
+Continue to [03 - Interactive Prompts](../03-interactive-prompts/).

projects/modules/02-cli-tools/02-multi-command-cli/notes.md

@@ -0,0 +1,10 @@
+# Notes -- Module 02 / Project 02 -- Multi-Command CLI
+
+## What I learned
+
+
+## What confused me
+
+
+## What I want to explore next
+

projects/modules/02-cli-tools/02-multi-command-cli/project.py

@@ -0,0 +1,124 @@
+"""Module 02 / Project 02 -- Multi-Command CLI.
+
+A file utility with three subcommands:
+  info  -- show file size and last-modified date
+  count -- count lines, words, and characters
+  head  -- print the first N lines
+
+Demonstrates click.group() for organizing related commands.
+
+Run it with:
+    python project.py info project.py
+    python project.py count project.py
+    python project.py head project.py --lines 10
+"""
+
+import os
+from datetime import datetime
+
+import click
+
+
+# @click.group() turns this function into a command group.
+# Instead of doing work itself, it acts as a dispatcher for subcommands.
+@click.group()
+def cli():
+    """A small file utility with info, count, and head subcommands."""
+    # The group function body usually stays empty.
+    # Click calls the appropriate subcommand after this runs.
+    pass
+
+
+# --------------------------------------------------------------------------- #
+# Subcommand: info
+# --------------------------------------------------------------------------- #
+
+# @cli.command() registers "info" as a subcommand of the cli group.
+@cli.command()
+# click.Path(exists=True) tells Click to verify the file exists
+# before the function even runs. If the file is missing, Click
+# prints a clear error and exits -- no try/except needed.
+@click.argument("filepath", type=click.Path(exists=True))
+def info(filepath):
+    """Show file size and last-modified date."""
+
+    # os.path.getsize returns the file size in bytes.
+    size = os.path.getsize(filepath)
+
+    # os.path.getmtime returns the modification time as a Unix timestamp.
+    # We convert it to a human-readable string.
+    mtime = os.path.getmtime(filepath)
+    modified = datetime.fromtimestamp(mtime).strftime("%Y-%m-%d %H:%M:%S")
+
+    # Print a tidy summary. The comma formatting (:,) adds thousand separators.
+    click.echo(f"File:     {filepath}")
+    click.echo(f"Size:     {size:,} bytes")
+    click.echo(f"Modified: {modified}")
+
+
+# --------------------------------------------------------------------------- #
+# Subcommand: count
+# --------------------------------------------------------------------------- #
+
+@cli.command()
+@click.argument("filepath", type=click.Path(exists=True))
+def count(filepath):
+    """Count lines, words, and characters in a file."""
+
+    # Read the entire file into memory.
+    # For very large files you would stream line by line, but for a
+    # learning project reading everything at once is clearer.
+    with open(filepath, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    # splitlines() breaks the text on any newline character.
+    lines = content.splitlines()
+
+    # split() with no arguments splits on any whitespace and
+    # ignores leading/trailing whitespace -- exactly what wc does.
+    words = content.split()
+
+    # len() on a string gives the character count (including newlines).
+    chars = len(content)
+
+    click.echo(f"Lines: {len(lines):,}")
+    click.echo(f"Words: {len(words):,}")
+    click.echo(f"Chars: {chars:,}")
+
+
+# --------------------------------------------------------------------------- #
+# Subcommand: head
+# --------------------------------------------------------------------------- #
+
+@cli.command()
+@click.argument("filepath", type=click.Path(exists=True))
+# --lines defaults to 5. The user can override it.
+@click.option(
+    "--lines", "-n",
+    default=5,
+    show_default=True,
+    help="Number of lines to display from the top.",
+)
+def head(filepath, lines):
+    """Show the first N lines of a file."""
+
+    with open(filepath, "r", encoding="utf-8") as f:
+        # Read all lines, then slice. For huge files you could use
+        # itertools.islice, but clarity wins here.
+        all_lines = f.readlines()
+
+    # Slice the list to get only the first N lines.
+    selected = all_lines[:lines]
+
+    # Print each line. rstrip() removes the trailing newline so
+    # click.echo does not double-space the output.
+    for line in selected:
+        click.echo(line.rstrip())
+
+
+# Entry-point guard.
+if __name__ == "__main__":
+    # Calling cli() hands control to Click's group dispatcher.
+    # Click inspects sys.argv, finds the subcommand name, and
+    # calls the matching function.
+    cli()