User guide

CLI reference

cli.py runs a grading session from a terminal or in CI. It uses the same GradingService as the web app and writes the same session to results/.

usage: musa-grader [-h] {grade,sessions,rubrics} ...

`grade`#

Grade a folder of submissions or a Canvas export ZIP.

python cli.py grade SUBMISSIONS [--rubric PATH] [--data PATH]... [--mode {docker,local}]
                    [--image IMAGE] [--timeout SECONDS] [--cell-timeout SECONDS]
                    [--confidence-threshold FLOAT]

Argument	Default	Description
`SUBMISSIONS`	required	A submissions folder or a Canvas export ZIP.
`--rubric`	`rubrics/hw1.yaml`	The rubric to grade against.
`--data PATH`	none	An assignment data file to place into every submission. Repeat the flag for several files. Students submit notebooks only, so Assignment 1 needs this.
`--mode`	`docker`	`docker` runs each notebook in the sandbox image. `local` runs student code on this machine without isolation.
`--image`	`musa-grader:latest`	The sandbox image for docker mode.
`--timeout`	`600`	Whole-notebook timeout in seconds. A rubric's `execution_timeout_seconds` raises it, never lowers it.
`--cell-timeout`	`300`	Per-cell timeout in seconds.
`--confidence-threshold`	`0.8`	Items graded below this confidence go to the review queue.

Before grading, the command prints warning: lines from GradingService.preflight(). Examples: no data file set for an assignment that needs one, a data path that does not exist, or one of Assignment 3's five files missing. If --mode docker is given and Docker is not running, it exits with status 2.

Example output#

7 submissions found in examples/submissions
[1/7] student_001
[2/7] student_002
...

✓ student_001: 100/100
✓ student_003: 71.5/100 · needs review
✕ student_005: 38/100 · needs review
...

# Assignment 1: The Donut Effect — class summary

- Submissions: 7
- Mean score: …
- Needing review: …
- Execution errors: …

## Most common issues
...

Saved to results/hw1_20261006_142233

The scores above are illustrative. Each line shows the execution icon (✓ ran, ✕ failed, — not run), the student, the score, and whether the submission needs review. The class summary that follows is the same markdown as class_report.md.

Examples#

# Assignment 1 in the sandbox, with the class's Zillow file
python cli.py grade examples/submissions --mode docker --data examples/data/zillow_zhvi.csv

# Assignment 2: no data, graded from saved outputs
python cli.py grade examples/hw2_submissions --rubric rubrics/hw2.yaml

# Assignment 3 with a longer budget for the raster work
python cli.py grade canvas_export.zip --rubric rubrics/hw3.yaml --timeout 1800 --cell-timeout 1800

`sessions`#

List saved grading sessions in results/: session id, assignment, submission count and last update.

python cli.py sessions

`rubrics`#

List every rubric in rubrics/ that parses, as assignment_id path. CI runs this to check that every rubric loads.

python cli.py rubrics

Exit codes#

Code	Meaning
`0`	Success. Submissions may still be flagged for review.
`2`	Rubric not found, or docker mode requested while Docker is unavailable.