e3cli

Moodle automation CLI — works with any Moodle instance
Sync courses, download materials, submit assignments, view announcements — all from your terminal.

Install • Quick Start • Commands • Interactive • Security • Claude Code • 繁體中文

Intended use: Finished your homework? Too lazy to open the browser? Submit it from CLI.

Unintended use: Let Claude Code auto-pull new assignments, finish them, and upload. (Please don't.)

Features

Login — Moodle Web Service API authentication with encrypted credential storage
Multi-profile — Multiple accounts with per-profile Moodle URL; switch profiles to switch schools instantly
Courses — List enrolled courses grouped by semester, view course intro
Assignments — View assignments with descriptions, deadlines, submission status, and attachments
Download — Batch download course materials (current semester by default)
Submit / Edit — Upload, submit, and re-upload (overwrite) assignments
Announcements — View course announcements and their content
Members — List course members (teachers and students)
Messaging — Send Moodle messages to course members
Sync — One command to pull everything new (materials + assignment status)
Schedule — Cron-based automatic sync
Interactive TUI — Full arrow-key interactive interface (e3cli i)
Bilingual — Full Chinese/English support
Multi-school — Works with any Moodle instance (configurable semester format)

Supported Platforms

Platform	Architecture	Status
macOS	Apple Silicon (ARM64)	✅ Supported
macOS	Intel (x86_64)	✅ Supported
Linux	x86_64	✅ Supported
Linux	ARM64	✅ Supported

Requires Python 3.11+.

Installation

Homebrew (recommended)

brew tap junlinwk/e3cli
brew install e3cli

pipx

pipx install git+https://github.com/junlinwk/e3cli.git

pip

pip install git+https://github.com/junlinwk/e3cli.git

From source

git clone https://github.com/junlinwk/e3cli.git
cd e3cli
pip install -e ".[dev]"

After installation, e3cli is available as a system-wide command.

Upgrade

Method	Command
Homebrew	`brew update && brew upgrade e3cli`
pipx (GitHub)	`pipx install git+https://github.com/junlinwk/e3cli.git --force`
pipx (PyPI)	`pipx upgrade e3cli`
pip (PyPI)	`pip install e3cli --upgrade`

Quick Start

# 1. Login (first time — interactive setup wizard will guide you)
e3cli login --save

# 2. List your courses
e3cli courses

# 3. Download all course materials
e3cli download

# 4. Check assignments and deadlines
e3cli assignments

# 5. Submit an assignment
e3cli submit <assignment-id> homework.pdf

# 6. Launch interactive mode
e3cli i

Commands

`e3cli login`

Authenticate with your Moodle account and store the API token.

e3cli login                    # Interactive prompt
e3cli login -u <student-id>    # Specify username
e3cli login --save             # Save credentials (encrypted) for auto-refresh
e3cli login --refresh          # Re-authenticate using saved credentials

`e3cli logout`

Securely erase all stored credentials and tokens.

e3cli logout

`e3cli courses`

List enrolled courses grouped by semester.

e3cli courses                  # Current semester only
e3cli courses --all            # All semesters
e3cli courses --semester 1142  # Specific semester

`e3cli assignments`

View assignments with deadlines, submission status, descriptions, and attachment counts. Sorted by urgency (upcoming first, expired middle, submitted last).

e3cli assignments                  # Current semester
e3cli assignments --due-soon 7     # Due within 7 days
e3cli assignments --all            # All semesters
e3cli assignments --detail <ID>    # Full description + attachments for one assignment

`e3cli download`

Download course materials to local disk (current semester by default).

e3cli download                     # Current semester (default)
e3cli download --all               # All semesters
e3cli download --course "OS"       # Fuzzy match by course name/code
e3cli download --select            # Interactive course selection

Files are saved to ~/e3-downloads/<course>/<section>/ by default. Already-downloaded files are skipped automatically (tracked via SQLite).

`e3cli submit`

Upload and submit an assignment.

e3cli submit <assignment-id> file1.pdf file2.zip
e3cli submit <assignment-id> report.pdf --text "Some notes"
e3cli submit <assignment-id> late-hw.pdf --force     # Submit past deadline

Re-submitting to the same assignment ID will overwrite the previous submission.

`e3cli announcements`

View course announcements.

e3cli announcements -c "OS"                # List announcements
e3cli announcements -c "OS" --detail <ID>  # View full content + attachments

`e3cli members`

List course members with roles and email.

e3cli members -c "OS"          # Teachers listed first

`e3cli message`

Send a Moodle message to a user (recipient receives notification based on their settings).

e3cli message <user-id> "Hello"    # Direct message
e3cli message <user-id>            # Interactive multi-line input

`e3cli sync`

Pull all new materials and update assignment status in one command.

e3cli sync                     # Current semester (default)
e3cli sync --all               # All semesters
e3cli sync --course "OS"       # Specific course
e3cli sync --quiet             # Silent mode (for cron)

`e3cli schedule`

Manage automatic sync via system crontab.

e3cli schedule enable                  # Default: every 60 minutes
e3cli schedule enable --interval 30    # Every 30 minutes
e3cli schedule disable                 # Remove cron job
e3cli schedule status                  # Show current schedule

`e3cli profile`

Manage multiple accounts. Each profile stores its own credentials, token, and Moodle URL, so you can switch between different schools instantly.

e3cli profile                  # List all profiles (with school URL)
e3cli profile use <name>       # Switch to a profile (also switches Moodle URL)
e3cli profile remove <name>    # Remove a profile

When switching profiles via e3cli profile use or the interactive TUI, the Moodle URL in config.toml is automatically updated to match the profile's school.

# Login to a different school with a new profile
e3cli login --profile nycu --url https://e3p.nycu.edu.tw --save
e3cli login --profile ntu --url https://cool.ntu.edu.tw --save

# Switch between schools
e3cli profile use nycu    # → connects to NYCU E3
e3cli profile use ntu     # → connects to NTU COOL

`e3cli setup`

Re-run the interactive setup wizard (language, Moodle URL, semester format, alias, download directory, login).

e3cli setup

`e3cli version`

e3cli version

Interactive Mode

Launch with e3cli i for a full TUI experience with arrow-key navigation:

╭──────────────── e3cli v0.5.0 ────────────────╮
│  王小明  |  114學年第2學期  |  6 courses      │
╰──────────────────────────────────────────────╯

────────────────── 主選單 ──────────────────────
❯ 選擇課程 (114學年第2學期)
  選擇課程 (所有學期)
  作業
  同步課程
  離開

↑↓ navigate  →/Enter select  ← back  / search
────────────────────────────────────────────────

Navigation

Key	Action
`↑` `↓`	Move selection
`→` / `Enter`	Enter selected item
`←` / `Esc`	Go back
`/` or type	Search / filter
`q`	Quit / back

Profile Menu

Select "Profile" from the main menu to:

Switch between profiles (auto-reloads with the new school's data)
Edit a profile (change Moodle URL, username, password)
Delete a profile (cannot delete the active one)
Add a new profile with a different school URL

Course Menu

Enter a course to access:

Course Intro — View course description
Materials — Browse and download files (with download status)
Assignments — View with descriptions, attachments, submission status; submit or re-upload
Announcements — Read course announcements
Members — View member list, send messages directly
Grades — View grade items

Assignment Detail

Select an assignment to see:

Full description (HTML rendered as text)
Attachment list with download
Currently submitted files
Submit (s) or Edit/re-upload (e) with tab-completion file picker
Shell mode (!) for terminal commands within the file picker

File Picker Features

When submitting or re-uploading:

Shows current directory and file listing
Tab completion for file paths (like your shell)
!command to run a shell command (e.g., !ls -la)
! alone to enter interactive shell mode (type exit to return)
Confirmation prompt before uploading

Configuration

Config file location: ~/.e3cli/config.toml

[moodle]
url = "https://e3p.nycu.edu.tw"
service = "moodle_mobile_app"

[storage]
download_dir = "~/e3-downloads"

[schedule]
interval_minutes = 60
notify = true

[general]
lang = "zh"              # "zh" or "en", or omit for auto-detect
semester_format = "nycu"  # "nycu", "western", "none"
alias = ""                # custom command name (e.g. "moodle")

Semester Format

Format	Schools	Example
`nycu` (default)	NYCU, NTU, and other Taiwan universities	`1142` = year 114, semester 2
`western`	Western year-based systems	`2025`
`none`	Any school (no filtering)	All courses treated as current

Auto-created with defaults on first run. Edit to customize, or run e3cli setup to reconfigure interactively.

Security

Credential Storage

e3cli uses PBKDF2-HMAC-SHA256 key derivation with integrity verification to protect stored credentials:

~/.e3cli/profiles/<name>/
  key               # 256-bit random encryption key  (chmod 600)
  credentials.enc   # Encrypted username + password   (chmod 600)
  token             # Moodle API token                (chmod 600)
  profile.json      # Moodle URL and service config

Measure	Detail
Encryption	PBKDF2-HMAC-SHA256 (100k iterations) + XOR stream cipher
Integrity	HMAC-SHA256 verification on every read
File permissions	`chmod 600` — owner-only read/write
Password input	`getpass` — never appears in shell history or CLI args
Logout	`e3cli logout` overwrites files with zeros before deletion
Key separation	Encryption key and encrypted data stored in separate files

What's NOT Stored

❌ No plaintext passwords on disk
❌ No credentials in config.toml
❌ No credentials in environment variables
❌ No credentials in shell history

Recommendations

Use e3cli login --save only on machines you trust
Run e3cli logout when done on shared machines
The ~/.e3cli/ directory is in .gitignore — never commit it

Claude Code Integration

This project includes a CLAUDE.md file that teaches Claude Code how to use e3cli as an automated assistant. When Claude Code is invoked in this project directory, it can:

Sync and check for new assignments (e3cli sync)
Read assignment descriptions and downloaded materials
Help complete assignments (with human oversight)
Submit completed work (e3cli submit)

See CLAUDE.md and e3cli/agent_prompt.md for the full agent automation guide.

Note: Claude Code will always ask for confirmation before submitting assignments.

Local Data

Path	Purpose
`~/.e3cli/config.toml`	User configuration
`~/.e3cli/token`	Active profile's Moodle API token (chmod 600)
`~/.e3cli/active_profile`	Active profile name
`~/.e3cli/profiles/<name>/`	Per-profile credentials, token, key, and Moodle URL
`~/.e3cli/data/e3cli.db`	SQLite tracking DB
`~/e3-downloads/`	Downloaded course materials

Development

git clone https://github.com/junlinwk/e3cli.git
cd e3cli
make dev       # pip install -e ".[dev]"
make lint      # ruff check
make test      # pytest
make build     # python -m build

Roadmap

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 49 Commits
.github/workflows		.github/workflows
Formula		Formula
e3cli		e3cli
gk		gk
hooks		hooks
info		info
logs		logs
objects		objects
refs		refs
scripts		scripts
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
COMMIT_EDITMSG		COMMIT_EDITMSG
HEAD		HEAD
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README_zh-TW.md		README_zh-TW.md
config		config
description		description
index		index
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

e3cli

Features

Supported Platforms

Installation

Homebrew (recommended)

pipx

pip

From source

Upgrade

Quick Start

Commands

e3cli login

e3cli logout

e3cli courses

e3cli assignments

e3cli download

e3cli submit

e3cli announcements

e3cli members

e3cli message

e3cli sync

e3cli schedule

e3cli profile

e3cli setup

e3cli version

Interactive Mode

Navigation

Profile Menu

Course Menu

Assignment Detail

File Picker Features

Configuration

Semester Format

Security

Credential Storage

What's NOT Stored

Recommendations

Claude Code Integration

Local Data

Development

Roadmap

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Contributors 1

Languages

`e3cli login`

`e3cli logout`

`e3cli courses`

`e3cli assignments`

`e3cli download`

`e3cli submit`

`e3cli announcements`

`e3cli members`

`e3cli message`

`e3cli sync`

`e3cli schedule`

`e3cli profile`

`e3cli setup`

`e3cli version`

Packages