canvas-grade-manager

CLI tool I built to deal with Canvas grading stuff that's annoying to do by hand.

The main thing it solves: Canvas penalizes students who submit even 1 second late. We give a 5-minute grace period, but Canvas doesn't care — it just docks points. So every lab, someone has to go into SpeedGrader and manually undo the penalty for students who were only a few minutes late. This does that automatically.

I ended up adding a few more things while I was at it.

What it does

• Grace period fix — finds students who submitted within 5 min of the deadline and removes their late penalty in bulk
• Download submissions — pulls all student files for an assignment into a local folder, sorted by name
• Status report — quick stats for any assignment (how many graded, average score, late count, etc.)
• Grading history — shows progress across all labs in one table so you can see what still needs grading

Setup

You need a Canvas API token. Go to Canvas → Account → Settings → scroll to Approved Integrations → generate a new token. Copy it.

Then install:

npm install canvas-grade-manager

Add your token to the .env in your cs546-labs repo (or wherever you grade from):

CANVAS_API_TOKEN=your_token_here
CANVAS_BASE_URL=https://sit.instructure.com

It searches up the directory tree for the .env, so you can run it from any subfolder.

Usage

npx canvas-grader

That opens a menu:

  Canvas Grade Manager v1.0.9
  CS 546 — Stevens Institute of Technology

? What do you want to do?
❯ Remove late penalties (grace period)
  Download student submissions
  View submission status report
  View grading history (all labs)
  ──────────────
  Exit

Pick an option, enter the course/assignment ID when it asks, and it handles the rest. For the grace period fix, it shows you exactly who will be affected and asks for confirmation before touching anything.

Where to find IDs

Just look at the Canvas URL:

https://sit.instructure.com/courses/85261/assignments/651254
                                     ^^^^^             ^^^^^^
                                   course id       assignment id

Grading history config

The history feature needs to know which assignment IDs map to which labs. Create a canvas-grader.config.json in your repo root:

{
  "assignments": {
    "1": { "courseId": "85261", "assignmentId": "651249" },
    "2": { "courseId": "85261", "assignmentId": "651252" },
    "3": { "courseId": "85261", "assignmentId": "651253" }
  }
}

You only set this up once per semester.

Using it in scripts

You can also import the functions directly if you want to plug them into your grader:

import { getSubmissions, updateSubmission } from "canvas-grade-manager/lib/submissions.js";
import { getStatus, getHistory, loadConfig } from "canvas-grade-manager/lib/report.js";
import { downloadSubmissions } from "canvas-grade-manager/lib/download.js";

const { lateSubmissions, actuallyLate } = await getSubmissions("85261", "651254");

// remove penalties
await updateSubmission("85261", "651254", lateSubmissions);

// get stats
const status = await getStatus("85261", "651254");

// download files
await downloadSubmissions("85261", "651254", "./submissions");

File structure

├── bin/cli.js           # the interactive menu
├── lib/
│   ├── canvas.js        # API wrapper (handles pagination)
│   ├── submissions.js   # grace period filtering + updates
│   ├── display.js       # table formatting
│   ├── download.js      # file downloads
│   └── report.js        # stats + history
├── canvas-grader.config.json
└── .env

Questions? Ping Harshil on Slack.