d2l-cli

d2l-cli

A terminal client for D2L Brightspace, set up for the University of Waterloo's Learn (learn.uwaterloo.ca).

Run d2l to browse your courses and their content, open files in the app you choose, and download them into the current directory. It also shows announcements, assignment due dates with submission status, and grades, and has fuzzy search.

Install

Download a binary for your platform from the releases page, or build it with Go:

go install github.com/BalajiLeninrajan/d2l-cli/cmd/d2l@latest

Logging in needs a Chromium-based browser (Chrome, Chromium, Brave, Edge, Vivaldi) or a Firefox-based one (Firefox, Zen, LibreWolf, Floorp).

d2l is developed and tested on Linux. It builds for macOS and Windows, but neither is tested or supported.

Logging in

d2l login

Learn has no API keys for students, so d2l uses a browser session. d2l login opens your default browser in a separate window with a profile of its own, on Learn's login page. Sign in through Waterloo SSO and Duo as usual. Once Learn accepts the session, d2l saves it and closes the window. It prints who you are logged in as.

d2l launches the browser with its automation port open and reads the cookies from that window, over the Chrome DevTools Protocol for Chromium-based browsers or WebDriver BiDi for Firefox-based ones. It never reads your normal browser profile, so your other tabs and logins stay out of it.

The default browser comes from xdg-settings. Flatpak and Snap installs work; their login profile lives inside the app's sandbox folder. If the default can't be driven (GNOME Web, for example), d2l uses the first supported browser it finds and says which. To pick one yourself, set browser in the config to a path or command.

The login profile stays between logins (~/.local/state/d2l/browser/<name>, or ~/.var/app/<id>/data/d2l-login for Flatpak). If you picked "stay signed in" at SSO, later logins first try a hidden window and often finish without showing anything. Pass -i to skip that attempt and show the window right away.

The session is stored with mode 0600 in ~/.local/state/d2l/session.json. Sessions expire. When d2l says the session expired, run d2l login again.

If the browser login does not work on your machine, for example over SSH with no display, copy the d2lSessionVal and d2lSecureSessionVal cookies from a logged-in browser tab and paste them in:

d2l login --cookie -

It asks for d2lSessionVal=...; d2lSecureSessionVal=... without echoing it. It also reads that line from a pipe. Passing the cookies as the flag value works too, but then they end up in your shell history.

d2l logout deletes the saved session. d2l logout --all also deletes the login browser profiles, so the next login starts from scratch.

Usage

Keys

In the courses list:

Inside a course, 1 to 4, tab and shift+tab switch between the Content, Announcements, Assignments and Grades tabs. f searches the course, r reloads the tab, esc goes back and q closes the current screen.

Opening a file downloads it to the cache first if the cached copy is missing or out of date. Pages that only work on Learn, such as quizzes, open in the web browser.

Quitting while downloads are running asks you to press q again. The downloads stop and their partial files are removed.

In search, type to narrow the results and press enter to keep the filter. Then enter opens a result, d downloads it and w opens it on Learn.

Press / in any list to filter it. esc clears the filter.

Configuration

The config file lives at ~/.config/d2l/config.toml. Run d2l config to create it with the defaults.

base_url = "https://learn.uwaterloo.ca"
concurrency = 4

# Browser used by "d2l login", as a path or command. Leave unset to use the
# default browser. Chromium- and Firefox-based browsers work.
# browser = "/usr/bin/chromium-browser"

# Files open with xdg-open unless the extension is listed here.
# The file path is appended as the last argument.
[openers]
pdf = "zathura --fork"
pptx = "libreoffice"

# Openers that need the terminal. The TUI suspends while they run.
[terminal_openers]
md = "nvim"
txt = "less"

Opener commands run through sh, so they can include arguments.

Where files go

d saves into the directory you started d2l from. A single file lands there as is. A folder or a whole course keeps its structure, one subfolder per module:

./CS 135/
  Week 1/
    lec01.pdf

Announcement attachments go straight into the current directory.

d2l never overwrites a file in the current directory. If one with the same name exists, it leaves the file alone and warns you in the status bar. To get a newer version from Learn, delete or rename your copy and press d again.

When two files in one module have the same name, the older topic keeps the name and the others get their topic ID added, as in handout (48213).pdf. Folders with the same name get the same treatment.

Files you open are downloaded to ~/.cache/d2l ($XDG_CACHE_HOME/d2l if set) with the same layout, and the content list marks them as cached. d2l sets each cached file's modification time to when it last changed on Learn, and downloads it again once Learn has a newer version. Edits saved in place to a cached file are lost when that happens. d2l clean deletes the cache.

How it works

d2l talks to the Brightspace Valence REST API using your session cookies, the same way the Learn website does. It asks the server which API versions it supports and uses the newest. If the server does not answer, it falls back to lp 1.49 and le 1.82.