why almost everything is a dry run
most canvas-sak commands that change your course do nothing the first time you run them. that’s deliberate, and it’s the most important thing to understand about the tool.
the problem it solves
canvas-sak operates in bulk. one command can move every due date in a course, overwrite every page, or push a letter grade to every student. the web ui makes that kind of mistake slowly and visibly — you’d notice around the fourth wrong due date. a command line makes it instantly and silently.
there is also no undo. canvas has no “revert my last bulk change” button. if you set 40 due dates to the wrong semester, fixing it means setting 40 due dates again, and any student who saw the wrong one in between has already emailed you.
so the default is inverted from what you might expect: the command shows you what it would do, and stops.
# shows what would change — nothing is written
canvas-sak set-due-dates "CS 146" dates.txt
# actually writes it
canvas-sak set-due-dates "CS 146" dates.txt --no-dryrun
the intended workflow is to run it, read the output, and only then re-run with
--no-dryrun. the dry run isn’t a safety net you’re meant to skip — it’s the part
where you check your data file was right.
which commands do this
16 of the 32 commands take --dryrun/--no-dryrun, and for those the default is always
--dryrun:
archive-inbox · code-similarity · derive-assignment-score ·
download-course-content · download-submissions · grade-discussion ·
grade-submission · rubrics · set-due-dates · set-fudge-points ·
set-letter-grade · settings-navigation · todo · update-assignment-groups ·
upload-assignment-grades · upload-course-content
⚠️ which commands do not
these commands write to canvas immediately, with no dry run and no confirmation prompt. there is no preview step — when you press enter, it has happened:
| command | what it does the moment you run it |
|---|---|
message-students |
sends the message |
announcement create |
posts the announcement |
update-assignment |
edits assignment settings |
update-quiz |
edits quiz settings |
set-course-image |
changes the course image |
upload-qti-quiz |
starts a content migration that imports the quiz |
this is an inconsistency in the tool, not a considered exception — the project’s own
convention says anything that modifies canvas should default to a dry run. until that’s
fixed, treat these six as live-fire and check the arguments before pressing enter.
message-students in particular cannot be taken back.
if you’re contributing a new command that writes to canvas, add the --dryrun flag —
see CONTRIBUTING.md.
a related habit
several commands accept a partial course name and refuse to run if it matches more than one course. that’s the same instinct: it would rather stop and ask than guess which course you meant. see how courses are found.