course-setup

CLI tools for setting up and retiring GitHub-backed course repositories.

Installation

Install as a uv tool (recommended):

uv tool install course-setup

This makes setup-course, retire-course, unretire-course, archive-course, list-courses, and setup-course-config available on your PATH. All six commands support --version and --help, which display the version number, PyPI URL, author name (Reuven Lerner), and email. To upgrade:

uv tool upgrade course-setup

You can also install with pip (pip install course-setup).

Configuration

Generate a starter config file:

setup-course-config

This creates a config.toml file in your platform's config directory (e.g., ~/Library/Application Support/course-setup/ on macOS, ~/.config/course-setup/ on Linux, %APPDATA%\course-setup\ on Windows). Open it and fill in your settings:

[github]
token = "ghp_YOUR_TOKEN_HERE"

[paths]
archive = "/path/to/your/archive"
# readme_source = "/path/to/custom/README.md"   # or a URL

[defaults]
notebook_type = "jupyter"   # or "marimo"

To regenerate the config file, use setup-course-config --force.

Usage

setup-course — Create a new course repo

setup-course -c Acme -t python-intro

Dependency groups

You can also define custom groups in your config.toml under [extras]. Entries can be package names or references to other groups (built-in or custom):

[extras]
finance = ["yfinance", "pandas-datareader"]
reuven = ["python", "data", "plotly"]   # expands python & data groups + plotly

Example — a Pandas course with Python extras and data/viz packages:

setup-course -c Acme -t pandas --extras python data

This will:

1. Create a directory and GitHub repo named {client}-{topic}-{YYYY-MM} (public by default; use --private for private)
2. Create a notebook per session, named {client}-{topic}-{YYYY-MM-DD} (.ipynb for Jupyter, .py for Marimo)
3. Generate a pyproject.toml with the notebook dependency and gitautopush
4. Include a .gitignore for Python, virtual environments, and IDE files
5. Configure the local .git/config with the GitHub SSH remote
6. Make an initial commit and push to GitHub
7. Run uv sync to install all dependencies

By default, a single notebook is created for today's date. Use -n to create multiple notebooks for multi-day or multi-week courses:

setup-course -c Acme -t python-intro -n 5              # 5 daily sessions
setup-course -c Acme -t python-intro -n 5 --freq weekly # 5 weekly sessions

retire-course — Archive a course repo

retire-course ./Acme-python-intro-2026-03

This will (for each directory):

1. Make the GitHub repo private (unless --keep-public is passed)
2. Move the local directory to your configured archive path under the current year (prompts for confirmation if the year directory doesn't exist)
3. Print a retirement summary showing: notebook count, date range, dependencies, archive location, and GitHub URL

With --dry-run, none of that happens: the GitHub repo is not touched, the archive directory is not created, and the course directory is not moved. Instead, retire-course prints a [DRY RUN] banner followed by the same retirement summary the real run would show. It reads your config file but makes no GitHub API calls, so a dry run touches nothing on the network. --dry-run applies to every directory passed on the command line.

You can retire multiple courses at once:

retire-course ./Acme-2026-03 ./Beta-2026-03 ./Gamma-2026-02

If any directory fails, the rest are still processed and errors are reported at the end.

Tip: run retire-course from the parent of the course directory, not from inside it. If you're already inside, the command detects it and tells you to cd .. rather than failing with a confusing error.

archive-course — Create a zip archive of a course

archive-course ./Acme-python-intro-2026-03

This archives all files in the course directory (.py, .csv, .toml, notebooks, etc.), excluding .git, .venv, __pycache__, and .ipynb_checkpoints directories. For Jupyter notebooks, each .ipynb is also exported to HTML and to PDF, and both are included alongside the original; use --no-html / --no-pdf to skip either export. PDF export is on by default, via nbconvert --to webpdf (headless Chromium — no LaTeX installation required). New Jupyter courses (3.3.1+) include the nbconvert[webpdf] dependency out of the box, and archive-course auto-installs the Chromium browser itself the first time it's needed — a one-time, per-machine download, with a status line printed while it installs. You no longer run any playwright command by hand — and if that automatic install ever fails (e.g. offline), archive-course prints the one-time uv run playwright install chromium command for you to run yourself, and still completes the archive with HTML. For a course created before 3.3.1, run uv add "nbconvert[webpdf]" in it once; archive-course still handles Chromium from there. If PDF export still can't run, archive-course prints a concise hint (not a traceback) and skips PDF — the rest of the archive (HTML exports, zip) is still produced. After creating the archive, a summary is printed listing the archive path, file count, size, notebooks (shown as notebook.ipynb + notebook.html + notebook.pdf), export counts, and all other included files.

Keeping the archive small enough to email. Course archives usually go to the client as a mail attachment, and a dataset left in the course directory can quietly push it past what mail will carry. If the finished zip exceeds --max-size (10 MB by default), archive-course lists the biggest files — largest first — and asks about each until the archive is under the limit, so one oversized dataset costs one question. The sizes it quotes are the files' compressed sizes read back from the archive itself, not their size on disk: a 19 MB CSV that deflates to 4.5 MB is reported as 4.5 MB, because that is what it actually costs you. Anything but an explicit y keeps the file, and whatever you leave out is named in the summary under Left out (too big to email):. The prompt only appears on a terminal — scripts, CI, and piped runs keep every file and print a warning instead — and --keep-all or --max-size 0 turn the questions off.

list-courses — List active and archived courses

list-courses

A read-only command: nothing is modified, and no GitHub API calls are made (it reads your config file, and each course's local git remote, but does not use the network).

Breaking change (3.2.0): the positional argument used to be a scan-directory override (list-courses ~/Other). It is now a name filter instead. To scan a different directory, use the repeatable --dir PATH flag: list-courses --dir ~/Other.

By default, list-courses prints the full list of active courses — a directory qualifies as a course if it has a .git subdirectory and at least one notebook (.ipynb, or a marimo .py) — followed by a one-line summary of the archived courses found under your configured [paths] archive directory (an archived course is any non-hidden, non-junk directory under a 4-digit-year folder that contains at least one notebook):

Active courses:
  Acme-python-intro-2026-03 — 5 notebooks (2026-03-17 → 2026-03-21)
    https://github.com/acme/python-intro-2026-03
  Beta-pandas-2026-02 — 3 notebooks (2026-02-02 → 2026-02-16)
    https://github.com/beta/pandas-2026-02

Archived: 412 courses across 2018–2026 — use --archived to list them.

Each course line is shown as name — N notebooks (first-date → last-date), with dates parsed from notebook filenames (n/a if none are found). By default, an indented line below each listed course (active courses, and archived courses in the expanded --archived/--year views) shows its GitHub URL, read from the course's local git origin remote — no network call. A course with no usable GitHub remote shows (no GitHub remote) instead. Pass --no-urls to hide these lines. URLs are not shown in the one-line archive summary or with --count.

Directories to scan for active courses are resolved in this order:

1. --dir PATH values passed on the command line (repeatable)
2. Otherwise, [paths] course_dirs from your config file
3. Otherwise, the current directory

Examples

If there are no matching active or archived courses, it prints an empty-state line (e.g. No active courses found, or No active courses match: cisco when a name filter excludes everything).

unretire-course — Restore a retired course

unretire-course /path/to/archive/2026/Acme-python-intro-2026-03

This will:

1. Make the GitHub repo public again
2. Move the directory from the archive back to your current working directory

Live teaching with gitautopush

In a separate terminal, run uv run gitautopush . from inside the course directory. This watches for notebook changes and automatically pushes them to GitHub, so students can follow along in real time by viewing the public repo.

Development

git clone https://github.com/reuven/course-setup.git
cd course-setup
uv sync --dev

Run tests, format, and lint:

uv run pytest
uv run ruff format src/ tests/
uv run ruff check src/ tests/
uv run mypy --strict src/

License

MIT — see LICENSE for details.