course-setup 2.9.0

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

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, and setup-course-config available on your PATH. 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 ~/.config/course-setup/config.toml. 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"

Setting	Required	Description
[github] token	Yes	GitHub personal access token. Alternatively, set the GITHUB_TOKEN environment variable.
[paths] archive	Yes	Directory where retired courses are archived.
[paths] readme_source	No	Local path or URL to a custom README for new courses. Omit to use the bundled default.
[defaults] notebook_type	No	"jupyter" (default) or "marimo".
[defaults] verbose	No	true or false (default). Sets the default verbosity for setup-course.
[defaults] extras_group	No	Default dependency group when --extras is not passed (e.g. "python").

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

Flag	Description
-c, --client	Client name (required)
-t, --topic	Course topic (required)
-d, --date	YYYY-MM override (defaults to current month)
-n, --num-sessions	Number of sessions (creates one notebook per session)
--freq	Session frequency: daily or weekly (requires -n, defaults to daily)
--notebook-type	jupyter or marimo (overrides config default)
--extras	Dependency groups to add to the course pyproject.toml (see below)
--add-imports	Pre-populate notebooks with import statements from --extras groups
-v, --verbose	Show detailed output (paths, filenames, dependencies)
--dry-run	Preview what would be created without making any changes

Dependency groups

Group	Packages
python	ipython
data	numpy, pandas, xlrd, openpyxl, pyarrow
viz	matplotlib, seaborn, plotly
geo	geopandas, folium, shapely
db	duckdb, sqlalchemy
ml	scikit-learn

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}
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. Configure the local .git/config with the GitHub SSH remote
5. Make an initial commit and push to GitHub
6. 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

Argument	Description
DIRNAME...	One or more course directories to retire

This will (for each directory):

1. Make the GitHub repo private
2. Move the local directory to your configured archive path under the current year

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.

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.