course-dl

Download Blackboard course exports from Curtin University's LMS as Common Cartridge packages, useful for migrating courses to Canvas or other LMS platforms.

Installation

uv tool install course-dl
playwright install chromium

Or install from source:

git clone https://github.com/michael-borck/course-dl.git
cd course-dl
uv sync
uv run playwright install chromium

Usage

Exporting is a two-step process because Blackboard takes 15–30 minutes to build each Common Cartridge package.

Step 1: Trigger builds

# Trigger builds for specific courses (fuzzy-matched)
course-dl build COMP1000 "Data Structures"

# Trigger builds for all courses
course-dl build --all

# Only courses from a specific teaching period
course-dl build --term "Semester 1 2025"
course-dl build --term 2025 --all

# Interactive picker — no args, select from a list
course-dl build

Blackboard queues the export and confirms with "This action has been queued." You can trigger builds for many courses at once — they build in parallel on the server.

Step 2: Download packages

Wait 15–30 minutes, then download with the same search terms:

# Download matching courses
course-dl download COMP1000 "Data Structures"

# Download all
course-dl download --all

# Interactive picker
course-dl download

Courses with no package ready yet will show "not ready" — just run the command again later.

Typical batch workflow

# 1. Trigger all builds
course-dl build --all

# 2. Wait 15-30 minutes...

# 3. Download everything
course-dl download --all -o exports/

Common options

course-dl [OPTIONS] {build,download}

Options (before subcommand):
  -u, --username STR    Curtin username
  -p, --password STR    Curtin password
  --visible             Show the browser window (default: headless)
  --timeout INT         Navigation timeout in ms (default: 60000)

Subcommand options:
  SEARCH...             Search terms (fuzzy-matched against course titles)
  -f, --file PATH       File with search terms (one per line)
  --all                 Select all courses
  --term STR            Only courses whose title contains STR (e.g. '2025')
  --match-threshold INT Fuzzy match score 0-100 (default: 60)

Download-only options:
  -o, --output-dir PATH Output directory (default: ./exports/)
  --overwrite           Re-download courses that already exist locally

Fuzzy matching

Course titles in Blackboard are long. You don't need the full title:

course-dl build COMP1000              # matches by unit code
course-dl build "Unix and C"          # matches by partial name
course-dl build "Data Structures"     # matches by topic

Interactive picker

When no search terms are provided, a numbered selection prompt is shown. Enter numbers separated by commas or spaces, with optional ranges:

Selection: 1          # just the first course
Selection: 1,3-5      # first course plus courses 3 to 5
Selection: all        # everything
Selection:            # (empty) cancel

Older year/semester courses

The course list includes all your Blackboard enrolments — past semesters included (the tool pages through Ultra's lazy-loaded list automatically).

To target older offerings:

# Narrow by teaching period, then pick interactively
course-dl build --term "Semester 1 2025"

# Or combine --term with --all
course-dl download --term 2024 --all -o exports/

# Or list past unit codes/names in a file (fuzzy-matched)
cat my-units.txt
ISAD1000
"Unix and C"
course-dl build -f my-units.txt

Note: only courses still visible in your Blackboard enrolment list can be exported. If Curtin has removed your enrolment from an old site, it won't appear regardless of --term.

Skip behaviour

course-dl download skips courses that already have a .zip or .imscc file in the output directory matching the unit code. Use --overwrite to force re-download.

When only one package exists on Blackboard, it is deleted after download (since we created it). When multiple packages exist, none are deleted and the tool logs which one was downloaded.

Credentials

Credentials are resolved in order:

1. CLI flags (-u, -p)
2. Environment variables (CDL_USERNAME, CDL_PASSWORD)
3. .env file (searched in order):
   • ~/.config/course-dl/.env
   • ~/.course-dl.env
   • ./.env
4. Interactive prompt

Copy .env.example to one of the above locations:

cp .env.example ~/.config/course-dl/.env

License

MIT