thu-learn-cli is a Rust client for THU's Web Learning (https://learn.tsinghua.edu.cn). It helps students inspect homework deadlines, read announcements, download course files, and submit homework from a terminal.
It has two front ends over the same Learn client:
- TUI for humans: run
thu-learnwith no arguments for an interactive, keyboard-driven interface. - CLI for scripts and agents: subcommands such as
thu-learn hw --jsonprint stable, scriptable output.
- Interactive TUI with homework, announcement, file, and course tabs, live search, course filters, downloads, and submission.
- Browser-based login through the official THU authentication flow.
- Stays logged in: like learnX, an expired Learn session is renewed automatically in the background.
- Homework listing, detail view, attachment download, and submission.
- Course announcement listing and detail view.
- Course file listing, detail view, and download.
- Structured JSON output for scriptable commands.
Each GitHub release has prebuilt binaries for macOS on Apple Silicon (aarch64-apple-darwin) and Linux on x86_64 (x86_64-unknown-linux-musl, statically linked, so it runs on any distribution). To install the latest one into ~/.local/bin:
target=aarch64-apple-darwin # or x86_64-unknown-linux-musl on Linux
curl -fsSL "https://github.com/lyrenius/thu-learn-cli/releases/latest/download/thu-learn-$target.tar.gz" | tar -xz
mkdir -p ~/.local/bin && mv "thu-learn-$target/thu-learn" ~/.local/bin/Each archive has a .sha256 file next to it for shasum -a 256 -c. The macOS binary is not signed: if you download it with a browser instead of curl, macOS refuses to run it until you remove the quarantine flag with xattr -d com.apple.quarantine thu-learn.
To build from source instead, run this from the repository root:
cargo build --releaseThe binary is written to target/release/thu-learn.
thu-learn # in a terminal; same as `thu-learn tui`
thu-learn tui -d ~/DownloadsThe screen shows a list on the left and details for the selected item on the right (stacked on narrow terminals). Every tab shows one semester, starting with Learn's current one; an earlier semester's ID turns yellow in the header while you view it. The TUI reuses the session saved by thu-learn login and, like the CLI, renews it automatically when it expires. If there is no usable session (or automatic re-login fails), it asks you to run thu-learn login and press r.
| Key | Action |
|---|---|
1-4, Tab, ←/→ |
Switch between Homework, Announcements, Files, and Courses |
↑/↓, j/k, PgUp/PgDn, g/G |
Move the selection |
Enter |
Open details full screen (in Courses: show that course's homework) |
J/K |
Scroll details; n/p move to the next/previous item while details are open |
/ |
Search the current list; Esc clears the search, then the file selection, then the course filter |
c |
Choose a course for every tab |
S |
Switch semester (or click the semester in the top-right corner) |
f |
Homework: cycle pending, overdue, done, all. Announcements: toggle unread only |
Space, v/V, C-a/C-r |
Files: select like yazi. Toggle and move down, visual select/unselect (move to extend the range, Esc applies it), select all, invert |
d |
Download the highlighted homework's attachments or the highlighted file; with files selected, every selected file |
s |
Submit a file for the selected homework through the file picker (below) |
D / o |
Change the download folder / open the last download |
r |
Refresh from Learn |
? / q |
Help / quit |
The mouse works as in yazi: click a tab to switch to it, click a row to select it, right-click a row to open it, and use the wheel to move through the list or scroll the details. Clicking a key hint presses its key, such as s submit a file at the end of a homework's details or / search in the bottom bar. Course choices and the [Y]es/(N)o buttons can be clicked too. While the TUI is open, the terminal's own text selection needs a modifier key: Shift in most terminals, Option in iTerm2 and Terminal.app.
Submitting opens a file picker that looks and behaves like yazi with its default keymap: parent, current, and preview columns (1:4:3), yazi's header and status bar, and the same keys. Press ~ or F1 inside the picker for the full list.
| Keys | Action |
|---|---|
j/k, ↑/↓ |
Next/previous file (wraps around) |
gg/G, C-u/C-d, C-b/C-f |
Top/bottom, half page, full page |
h/l, ←/→ |
Parent folder / enter folder |
H/L |
Back/forward in folder history |
Enter, o |
Choose the selected or hovered file (on a folder: enter it) |
Space, C-a, C-r |
Toggle selection, select all, invert |
f |
Filter the folder (regex, smart case, remembered per folder) |
/, ?, n, N |
Find next/previous, jump to next/previous match |
Esc |
Clear the find, then the filter, then the selection |
. |
Show hidden files |
,m ,b ,e ,a ,n ,s ,r (uppercase reverses) |
Sort by mtime, birth time, extension, name, natural, size, random |
ms mp mb mm mo mn |
Linemode: size, permissions, birth time, mtime, owner, none |
gh gc gd g<Space> gf |
Go home, ~/.config, ~/Downloads, typed path (with completion), follow symlink |
cc cd cf cn |
Copy path, folder, file name, name without extension |
J/K |
Scroll the preview |
Tab |
File details (spot) |
q, C-c |
Cancel the submission |
The mouse also follows yazi's defaults: in the middle column a click hovers a file, a right click chooses it (or enters a folder), and the wheel moves the cursor; a click in the left column goes to that entry (below the last one, to the parent folder); a click in the preview opens the folder at that entry, and the wheel scrolls the preview.
Input popups work like yazi's: they open in insert mode, Esc switches to a vi-style normal mode, and a second Esc closes them. Yanked or cut text goes to the system clipboard, and p/P paste text yanked, cut, or copied inside the picker (they do not read the system clipboard). After choosing a file, type an optional comment and press Enter; the confirmation shows the course, homework, file, and size before anything is sent, and n returns to the picker as you left it. Dragging a file into the terminal chooses it.
Differences from yazi, because the picker uploads exactly one file: Enter on a folder enters it instead of choosing it, choosing more than one file is refused, and keys that change files, run shell commands, use tabs, or call plugins (fd, rg, fzf, zoxide) show a notice instead, and the mouse is ignored while a popup is open. Folder listings refresh about once a second while the picker is open. The prebuilt Linux binary cannot read file birth times (a musl limitation), so there mb shows no times and ,b sorts by name. The picker opens in the download folder and then remembers the last folder you submitted from.
Downloads go to the current directory unless --dir or D says otherwise, and never overwrite an existing file (a (1) suffix is added). Downloading selected files asks first, saves them into one folder per course (for example Networks/Lab 1.pdf), and fetches four at a time. Detail panes show each item's short ID so it can be passed to CLI commands.
When stdout is not a terminal, thu-learn without a command prints help instead of starting the TUI, so scripts and agents never get stuck in an interactive screen.
Run:
thu-learn loginThe command asks for your THU username and password, then opens a Google Chrome window on THU's normal login page with both fields filled in. Complete any captcha and two-factor check there. When THU asks whether to trust the device, the CLI answers "yes" for its own random device ID. After the Learn home page is reached, the CLI checks that it can log in again over plain HTTP, and only then saves the credentials.
Learn sessions live on the server and expire after a period of inactivity, so saved cookies alone stop working quickly. thu-learn-cli handles this the way learnX does:
- The first login trusts a random device ID (
fingerPrint) during two-factor authentication. - The username, password, and that device ID are saved in the system credential store.
- When a request finds the session expired (Learn redirects to
login_timeoutor answers HTTP 403), the CLI logs in toid.tsinghua.edu.cnagain over HTTP. The password is SM2-encrypted exactly like the official login form does it. The CLI then opens Learn with the returned ticket and retries the request. Because the device ID is trusted, no two-factor prompt is needed.
You only need to run thu-learn login again if your password changes, or if THU stops trusting the device (for example, after you remove it from your account). The next thu-learn login reuses the saved device ID, so it usually succeeds without opening Chrome; use thu-learn login --browser to go through Chrome anyway, for example when THU asks for a captcha.
Failed logins are not repeated blindly, because repeated failures can make THU require a captcha. A network problem is retried after 30 seconds. Credentials that THU rejects (wrong password, or the device is no longer trusted) are not tried again, not even by later commands, until the next successful thu-learn login. This is recorded in ~/.config/thu-learn-cli/relogin-blocked.json, which holds only a hash of the rejected credentials.
- Credentials are stored in the macOS Keychain, Windows Credential Manager, or the Secret Service keyring on Linux. Only if no such store exists (for example, a headless Linux machine) do they go to
~/.config/thu-learn-cli/credentials.json, which only your user can read. A locked keyring, or a denied access prompt, is reported as an error instead. SetTHU_LEARN_CREDENTIAL_STORE=fileto always use the file, orkeyringto require the system store. thu-learn login --no-rememberkeeps the old behavior: only browser cookies are saved, no password is stored, and any previously saved credentials are removed.thu-learn logoutends the Learn session and deletes saved credentials (from the keyring and the fallback file), cookies, and cache. If any copy cannot be removed, it says so and exits with an error. THU may keep listing the device as trusted until you remove it from your account.
Requirements and storage behavior:
- Google Chrome must be installed locally.
- Chromedriver is downloaded and managed by
thirtyfour::WebDriver::managed. - Session cookies are stored at
~/.config/thu-learn-cli/cookies.jsonwith owner-only permissions. - Semester and course-list cache files are stored under
~/.cache/thu-learn-cli/. - Running
thu-learn loginclears the cache after logging in.
List entries show a seven-character short ID. Use that short ID, a unique short-ID prefix, or a full server ID for detail, download, and submit commands where supported.
thu-learn login
# Courses
thu-learn courses
# Homework
thu-learn hw
thu-learn hw -a
thu-learn hw --overdue
thu-learn hw -c <course>
thu-learn hw <id> # details and attachment names
thu-learn hw <id> -d ./dir # also download all of its attachments into ./dir
# Announcements
thu-learn ann
thu-learn ann -c <course>
thu-learn ann <id>
# Course files
thu-learn f ls
thu-learn f ls -c <course>
thu-learn f show <id>
thu-learn f get <id>
# Homework submission
thu-learn submit <id> ./hw.pdf -c "submission note"
# JSON output
thu-learn hw --json
# Another semester (1 = fall, 2 = spring, 3 = summer); works with every command
thu-learn hw -a --semester 2025-2026-1Notes:
- Human output uses color when stdout supports it;
--jsonoutput is plain structured data. - Lists and detail views end with the command to run next, such as
thu-learn hw <id> -d <dir>under a homework item with attachments. These hints go to stderr (except the olderDownload:line off show) and keep any--semesteryou gave, because short IDs are looked up within one semester. - Commands use Learn's current semester unless
--semesternames another;thu-learn --semester <ID>opens the TUI on that semester. - The current semester and course list are cached for six hours.
- Homework, announcement, and file requests are intentionally concurrent.
- Expired sessions are renewed automatically when credentials are saved. If automatic re-login fails, or after
login --no-remember, commands ask you to runthu-learn loginagain.
Recommended local checks:
cargo test
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo build --releaseFocused examples:
cargo test api::tests::parse_deadline_invalid
cargo test client::tests::csrf_extracted
cargo test cli::tests::semester_arg_rejects_malformed_ids
cargo test client::tests::expired_session_is_renewed_once_for_concurrent_requests
cargo test sso::tests::sm_crypto_fixture_decrypts_with_c1c3c2_layoutRe-login tests run against a local mock of Learn and id.tsinghua.edu.cn (src/mock_sso.rs), so they need no network access or account.
The hidden thu-learn debug command prints selected raw Learn API responses for field investigation. It requires a valid login session.
To release, set version in Cargo.toml, commit, and push a matching tag such as v0.1.0. The release workflow (.github/workflows/release.yml) checks formatting and lints, generates THIRD_PARTY_LICENSES.md, runs the tests on each target, builds the archives, and publishes them as a GitHub release. Running the workflow by hand from the Actions tab builds the archives without publishing anything.
THIRD_PARTY_LICENSES.md lists the license of every crate in the release binaries. It is generated with cargo-about from about.toml and about.hbs, and is not committed. A dependency under a license missing from accepted in about.toml fails the release until you review the license and add it. To generate the file locally:
cargo install --locked cargo-about@0.9.3 --features cli
cargo about generate --locked --fail about.hbs -o THIRD_PARTY_LICENSES.md~/.config/thu-learn-cli/cookies.json contains session credentials, and the thu-learn-cli entry in the system credential store (or the fallback ~/.config/thu-learn-cli/credentials.json) contains your THU password and trusted device ID. Do not print them, copy them into a repository, commit them, or share them. Rebuildable cache data is stored under ~/.cache/thu-learn-cli/. Automated tests should not require a live Web Learning account, Chrome, chromedriver, the system credential store, or an existing cookie file.
- Learn API behavior references thu-learn-lib (MIT, copyright 2019-2022 Harry Chen).
- Browser-login behavior references reserves-lib-tsinghua-downloader (GPL-3.0).
- Silent re-login behavior (trusted device ID, SM2 password encryption, ticket roaming) references learnX and its thu-learn-lib fork (MIT).
- The submission picker follows yazi's default keymap and behavior, and ports some of its code (MIT, copyright 2023 sxyazi). See THIRD_PARTY_NOTICES.md.
- Release archives include
THIRD_PARTY_LICENSES.mdwith the licenses of the Rust crates compiled into the binary.
This project is licensed under GPL-3.0-or-later.
Use this tool only with your own THU account and follow the Learn platform terms of service. Do not use it for bulk scraping or abuse.