CLI Reference¶
Auto-generated reference for all mograder commands and options.
mograder¶
mograder — Semi-automated grading for Marimo notebooks.
Usage:
Options:
autograde¶
Run notebooks and inject grading cells for marker review.
ASSIGNMENTS can be assignment names (e.g. "A1") which are auto-expanded to submitted/A1/*.py, or explicit file paths.
Usage:
Options:
--source PATH Source notebook (with solutions); auto-discovered
from source/ directory if omitted
--csv PATH Write verification results to CSV file
--moodle-csv PATH Moodle offline grading CSV (use with --moodle-zip)
--moodle-zip PATH Moodle submission ZIP (use with --moodle-csv)
-j, --jobs INTEGER Number of parallel workers
--timeout INTEGER Timeout per notebook in seconds
-o, --output-dir PATH Output directory for grading copies (default:
autograded/)
--force Re-autograde all submissions even if output is up to
date
--safety-check Scan submitted code for dangerous patterns before
execution
--max-memory INTEGER Max virtual memory per notebook in MB (overrides
config rlimits.as)
--help Show this message and exit.
feedback¶
Export graded notebooks to HTML and aggregate grades.
ASSIGNMENTS can be assignment names (e.g. "hw1") which are auto-expanded to autograded/hw1/*.py, or explicit file paths.
Usage:
Options:
-o, --output-dir PATH Output directory for HTML feedback (default:
feedback/)
--grades-csv PATH Write aggregated grades to CSV
--timeout INTEGER Timeout per notebook in seconds
-j, --jobs INTEGER Number of parallel workers
--no-penalties Skip late penalty computation even if configured
--due-date TEXT Override due date (ISO format or Unix timestamp)
--help Show this message and exit.
generate¶
Strip solutions from source notebooks to produce release versions.
ASSIGNMENTS can be assignment names (e.g. "demo-assignment") which are auto-expanded to source/demo-assignment/*.py, or explicit file paths.
Usage:
Options:
-o, --output-dir PATH Output directory (default: release/)
--dry-run Preview changes without writing files
--validate Only validate markers, don't generate output
--no-validate Skip source notebook validation (running checks)
--submit-url TEXT Inject a submit cell with this server URL into
release notebooks
--progress Emit JSON progress events to stderr (for grader UI)
--help Show this message and exit.
grader¶
Launch the grader dashboard for managing grading.
Usage:
Options:
-p, --port INTEGER Port for marimo app
--headless Don't open browser
--base-url TEXT Base URL path for reverse proxy
--help Show this message and exit.
grader-asgi¶
Launch the grader as a persistent ASGI service.
Uses uvicorn with trusted-proxy authentication middleware. Intended for deployment behind a reverse proxy (e.g. on sciml).
Usage:
Options:
-p, --port INTEGER Port for uvicorn
--host TEXT Bind address
--base-url TEXT Base URL path for reverse proxy
--instructors TEXT Comma-separated instructor user IDs
--trusted-proxies TEXT Comma-separated trusted proxy IPs
--reload Auto-reload on source changes (for development)
--help Show this message and exit.
https¶
HTTPS server transport: fetch, submit, upload grades.
Usage:
Options:
feedback¶
Check submission status and view grade/feedback.
Usage:
Options:
--url TEXT Server URL (overrides config)
--token TEXT Auth token (overrides cached token)
--help Show this message and exit.
fetch¶
Download assignment files from an HTTPS server.
Usage:
Options:
--list List available assignments
--url TEXT Server URL (overrides config)
--token TEXT Auth token (overrides cached token)
-o, --output-dir PATH Output directory (default: current dir)
--help Show this message and exit.
fetch-submissions¶
Download all submissions from an HTTPS server (instructor).
Usage:
Options:
--url TEXT Server URL (overrides config)
--token TEXT Instructor auth token
-o, --output-dir PATH Output directory
--force Re-download even if file exists
--help Show this message and exit.
login¶
Cache an HTTPS authentication token.
Usage:
Options:
--token TEXT HTTPS auth token [required]
--url TEXT Server URL (overrides config)
--help Show this message and exit.
submit¶
Submit a .py notebook to an HTTPS assignment server.
Usage:
Options:
--url TEXT Server URL (overrides config)
--token TEXT Auth token (overrides cached token)
--dry-run Show what would happen
--help Show this message and exit.
upload-grades¶
Upload grades to an HTTPS assignment server.
Usage:
Options:
--url TEXT Server URL (overrides config)
--token TEXT Instructor auth token
--grades-csv PATH Grades CSV file [required]
--dry-run Show what would happen
--help Show this message and exit.
hub¶
Multi-user hub server for mograder.
Run without a subcommand to start the hub server. Use subcommands (check, warm-cache, generate-token) for utilities.
Usage:
Options:
-C, --course-dir PATH Course directory (default: .)
--port INTEGER Port for hub server
--host TEXT Host to bind
--notebooks-dir PATH Directory for student notebooks
--session-ttl INTEGER Session idle timeout (s)
--trusted-header TEXT Trusted proxy header
--dev Dev mode: trust any X-Remote-User
--headless Don't open browser
--help Show this message and exit.
check¶
Preflight check: verify hub requirements.
Usage:
Options:
generate-token¶
Generate an HMAC authentication token for a user.
Usage:
Options:
publish¶
Publish a release assignment to the hub.
ASSIGNMENT is an assignment name (e.g. "A1-Intro-to-SciML" or prefix "A1") resolved from the release directory, or an explicit directory path.
By default, verifies the release files match what's on Moodle before publishing. Use --force to skip this check.
Usage:
Options:
--moodle-assignment TEXT Moodle assignment name to verify against (default:
same as ASSIGNMENT)
--url TEXT Hub base URL
--token TEXT Instructor token for hub API
--force Skip Moodle verification
--dry-run Verify only, don't publish
--no-warm Skip cache warming after publish
--help Show this message and exit.
sync-users¶
Sync allowed users to the hub from a file.
FILE contains one username per line (# comments allowed). Uploads the list to the hub's /sync-users endpoint.
For Moodle courses, use mograder moodle sync-users instead to
automatically fetch the enrolled user list.
Usage:
Options:
--url TEXT Hub base URL
--token TEXT Instructor token for hub API
--help Show this message and exit.
warm-cache¶
Warm the uv cache for notebook dependencies.
Parses PEP 723 inline script metadata to find dependencies,
then runs uv run --with <deps> python -c pass to populate the cache.
With --url, sends a POST to the hub's /warm-cache endpoint instead.
Usage:
Options:
--all Warm cache for all release notebooks
--dry-run Print deps but don't invoke uv
--url TEXT Hub URL — POST to remote /warm-cache instead of running
locally
--token TEXT Instructor token for remote warm-cache
--help Show this message and exit.
moodle¶
Moodle integration: fetch, submit, export grades, upload feedback.
Usage:
Options:
export¶
Merge grades into a Moodle offline grading worksheet.
Usage:
Options:
--worksheet PATH Moodle offline grading CSV (default:
import/<assignment>.csv)
--grades-csv PATH mograder grades CSV (auto-discovered from
gradebook.db if omitted)
--feedback-dir PATH Directory with {student}.html files; creates feedback
ZIP
-o, --output-dir PATH Output directory (default: export/)
--match-column TEXT Moodle CSV column to match student against (default:
Username)
--help Show this message and exit.
feedback¶
Check submission status and view grade/feedback for an assignment.
Usage:
Options:
-c, --course-id INTEGER Moodle course ID (overrides config)
--url TEXT Moodle URL (overrides config/env)
--token TEXT Moodle token (overrides env)
--help Show this message and exit.
fetch¶
Download assignment files from Moodle.
Usage:
Options:
--list List available assignments
-c, --course-id INTEGER Moodle course ID (overrides config)
--url TEXT Moodle URL (overrides config/env)
--token TEXT Moodle token (overrides env)
-o, --output-dir PATH Output directory (default: current dir)
--help Show this message and exit.
fetch-submissions¶
Bulk download all student submissions for an assignment (instructor).
Usage:
Options:
-c, --course-id INTEGER Moodle course ID (overrides config)
--url TEXT Moodle URL (overrides config/env)
--token TEXT Moodle token (overrides env)
-o, --output-dir PATH Output directory (default: submitted/<assignment>/)
--force Re-download even if file exists
--help Show this message and exit.
login¶
Obtain and cache a Moodle API token.
For sites with SSO (CAS, SAML, Shibboleth), use --sso to open a browser login flow. Otherwise, uses username/password via /login/token.php.
Usage:
Options:
--url TEXT Moodle URL (overrides config/env)
--sso Use browser-based SSO login (for sites with CAS/SAML/OAuth)
--help Show this message and exit.
submit¶
Upload a .py notebook as a Moodle assignment submission.
Usage:
Options:
-c, --course-id INTEGER Moodle course ID (overrides config)
--url TEXT Moodle URL (overrides config/env)
--token TEXT Moodle token (overrides env)
--no-finalize Save draft without submitting for grading
--dry-run Show what would happen without uploading
--help Show this message and exit.
sync¶
Sync assignment metadata from Moodle into mograder.toml.
Fetches assignment names, IDs, due dates, and file info from the Moodle API and writes them to the [moodle] section of mograder.toml. This metadata is used by the student dashboard to show assignments and open Moodle pages without requiring students to have API tokens.
Run this as an instructor whenever assignments change, then commit the updated mograder.toml so students get the latest info.
Usage:
Options:
-c, --course-id INTEGER Moodle course ID (overrides config)
--url TEXT Moodle URL (overrides config/env)
--token TEXT Moodle token (overrides env)
-i, --include TEXT Only include assignments matching this regex (e.g.
'^A[1-8]').
--edit-links Push edit links (molab, codespaces) into Moodle
assignment descriptions.
--help Show this message and exit.
sync-users¶
Sync enrolled Moodle users to the hub allowlist.
Fetches participants from the first Moodle assignment and pushes the username list to the hub's /sync-users endpoint. If --hub-url is not provided, writes allowed_users.txt locally instead.
Usage:
Options:
-c, --course-id INTEGER Moodle course ID (overrides config)
--url TEXT Moodle URL (overrides config/env)
--token TEXT Moodle token (overrides env)
--hub-url TEXT Hub URL to POST user list to (if omitted, writes
local allowed_users.txt)
--hub-token TEXT Instructor token for hub API
--dry-run Show users without syncing
--help Show this message and exit.
upload¶
Prepare release files for upload to a Moodle assignment.
Files are zipped into
Usage:
Options:
-c, --course-id INTEGER Moodle course ID (overrides config)
--url TEXT Moodle URL (overrides config/env)
--token TEXT Moodle token (overrides env)
--dry-run Show what would be uploaded
--open / --no-open Open Moodle edit page in browser
--help Show this message and exit.
upload-feedback¶
Upload grades and feedback to Moodle via API (instructor).
Usage:
Options:
-c, --course-id INTEGER Moodle course ID (overrides config)
--url TEXT Moodle URL (overrides config/env)
--token TEXT Moodle token (overrides env)
--feedback-dir PATH Directory with {student}.html feedback files
--grades-csv PATH Grades CSV (auto-discovered from gradebook.db if
omitted)
--dry-run Show what would be uploaded
--workflow-state TEXT Marking workflow state (default: readyforrelease).
Use 'released' to make visible immediately.
--help Show this message and exit.
serve¶
Start a lightweight assignment server.
Serves assignments from DIRECTORY (default: current dir).
Usage:
Options:
-p, --port INTEGER Port to listen on (default: $PORT or 8080)
--host TEXT Host to bind to (default: 0.0.0.0 if $PORT set,
else 127.0.0.1)
--no-auth Disable authentication (for local testing)
--generate-tokens PATH Read usernames from FILE, print tokens, then
exit
--enrollment-code TEXT Enrollment passphrase for student self-
registration
--enrollment-code-file PATH Read enrollment code from FILE
--release-dir PATH Serve files from
RELEASE_DIR/<assignment>/<file> (flat layout,
no files/ subdir)
--help Show this message and exit.
student¶
Launch the student course browser for fetching and submitting assignments.
COURSE_DIR_OR_URL can be a local directory (default: .) or an HTTPS URL to a mograder.toml config file for first-time setup.
Usage:
Options:
-p, --port INTEGER Port for marimo app
--headless Don't open browser
--no-token Disable marimo auth token
--help Show this message and exit.
sync¶
Sync autograded results to a remote server via rsync + SSH.
Usage:
Options:
--remote TEXT SSH host alias (default: from mograder.toml [sync]
remote)
--course-dir TEXT Course directory on remote (default: from mograder.toml
[sync] remote_course_dir)
--venv-dir TEXT Directory with uv venv on remote (default: from
mograder.toml [sync] remote_venv_dir)
--help Show this message and exit.
token¶
Generate authentication tokens for the given usernames.
Reads the HMAC secret via --secret-file, --secret-stdin, or --secret. With no flag, reads .mograder-secret from the current directory. Always appends an instructor token.
Usage:
Options:
--secret-file PATH Read secret from FILE
--secret-stdin Read secret from stdin
--secret TEXT Secret string (visible in process list)
--help Show this message and exit.
validate¶
Run notebook(s) in a sandbox and report check results.
ASSIGNMENTS can be assignment names (e.g. "A3-BayesianLinearRegression")
which are auto-expanded to source/
Usage:
Options:
--timeout INTEGER Timeout per notebook in seconds
--fix Restore modified non-solution cells from the release
version
--release PATH Path to release notebook (for --fix); auto-discovered
from .mograder/release/ if omitted
--help Show this message and exit.
wasm-edit-links¶
Inject pre-computed 'Edit in Molab' links into a WASM app source.
WASM_APP is the student_wasm_app.py file. NOTEBOOKS are the .py notebook files whose compressed content will be embedded as edit links. Each notebook's filename stem is used as the dict key (matching the server's assignment directory name convention).
Usage:
Options:
-o, --output PATH Output path for modified WASM app (default: overwrite
in-place)
--url-template TEXT URL template; {content_lz} is replaced with lzstring-
compressed content
--help Show this message and exit.
wasm-export¶
Check WASM compatibility and export compatible assignments.
With --check-only, prints a compatibility table without exporting. Without arguments, use --all to process all assignments.
Usage:
Options:
--all Export all WASM-compatible assignments
--check-only Only check compatibility, don't export
--mode TEXT WASM mode: edit or run
--help Show this message and exit.
workshop¶
Workshop notebooks with encrypted solutions.
Usage:
Options:
encrypt¶
Encrypt solutions in workshop notebooks.
Parses _exercises list, encrypts solution blocks, strips solutions, and injects solution-reveal cells. Output: workshop-ready marimo notebook.
Usage:
Options:
-o, --output-dir PATH Output directory (default: inferred from source path)
--salt TEXT Encryption salt (default: random)
--keys-url TEXT URL for keys.json (default: relative)
--help Show this message and exit.
export¶
Encrypt solutions and export as WASM HTML.
Same as encrypt, then runs marimo export html-wasm. Writes keys.json (empty) and keys_all.json.
Usage:
Options:
-o, --output-dir PATH Output directory for WASM export [required]
--salt TEXT Encryption salt (default: random)
--keys-url TEXT URL for keys.json (default: relative)
--help Show this message and exit.
release-key¶
Add one key to a keys.json for incremental release during a live workshop.
Usage:
Options:
serve¶
Serve a workshop export directory with an instructor dashboard.
Students open the root URL to use the WASM notebook. The instructor opens
/dashboard.html#token=
Usage:
Options: