name	canvas-cli
description	Use the local `canvas` CLI for Canvas LMS workflows. Trigger when you need to find a course, inspect modules/assignments/discussions/files/pages/people/grades/rubrics, or verify Canvas session status from the terminal.

Canvas CLI Agent Instructions

Run commands with the installed canvas executable. Prefer first-class canvas subcommands over raw tool calls. Use uv run canvas only when working inside this repository before installation.

Rules

Resolve a course before using course-scoped commands unless the user provided a course ID.
Use the narrowest first-class CLI command that answers the request.
Use canvas tool run only when no first-class subcommand exists, for debugging, or to mirror MCP tool behavior.
Preserve user privacy: never print cookie values, CSRF tokens, access tokens, or raw auth headers.
Summarize JSON output for the user. Do not paste large raw JSON unless requested.
Include exact IDs when they help the user follow up: course_id, assignment_id, topic_id, file_id.
If no matching Canvas object is found, say that directly and mention the search term/course checked.
If auth fails, run the auth recovery workflow before treating it as a code issue.
Treat quiz support as read-only.

Auth

canvas auth-status
canvas settings profiles
canvas settings choose-profile "<profile-name>"
canvas settings show
canvas settings clear

Use auth-status first when any Canvas command fails unexpectedly.

Auth recovery workflow:

Confirm the user is logged in to Canvas in Chrome, then rerun canvas auth-status.
If multiple Chrome profiles exist, run canvas settings profiles, choose the profile with Canvas cookies, then rerun canvas auth-status.
If the saved profile is stale or wrong, run canvas settings clear, then choose the profile again.
If Canvas host detection is wrong, use CANVAS_BASE_URL=https://school.instructure.com for subsequent commands.
On macOS, Keychain prompts for Chrome cookie access must be approved.

Course Resolution

canvas resolve "ENGL394" --all
canvas courses --all --search ENGL394
canvas tool run resolve_course --args '{"query":"ENGL394","favorites_only":false,"limit":10}'

Best practice:

Prefer canvas resolve for user-provided names like "ENGL394" or "business writing".
Use favorites_only=false when the user expects all active/past courses to be considered.
Confirm the resolved course name when multiple courses could match.

Assignments

canvas assignments list <course_id> --search infographic --limit 20
canvas assignments list <course_id> --bucket upcoming
canvas assignments list <course_id> --search infographic --include-submission
canvas assignments show <course_id> <assignment_id> --include-submission
canvas assignments groups <course_id> --assignments --include-submission

Best practice:

Search assignments by keyword before fetching details when the assignment ID is unknown.
Use assignments show for instructions, due dates, submission settings, discussion links, and attached rubric fields.
Use assignment aliases only as lookup aids; report canonical assignment IDs in final answers.

Rubrics

canvas assignments rubric <course_id> <assignment_id>
canvas assignments rubric <course_id> <assignment_id> --include-assessment

Best practice:

Use assignments rubric when the user asks for grading criteria, rubric categories, points, or how an assignment will be evaluated.
Use --include-assessment only when the user asks how they were graded or wants rubric feedback for their own submission.
Report rubric title, total points, criteria names, point values, and rating levels.
Do not assume use_rubric_for_grading=true; report its value if relevant.
If the assignment has no rubric, say so and suggest checking assignment details/comments instead.

Example workflow:

canvas resolve "ENGL394" --all
canvas assignments list 1402756 --search infographic --limit 20
canvas assignments rubric 1402756 7543238

Discussions

canvas discussion list <course_id>
canvas discussion list <course_id> --search planning
canvas discussion list <course_id> --graded
canvas discussion list <course_id> --search "week 2" --search-in title_or_message
canvas discussion show <course_id> <topic_id>
canvas discussion show <course_id> <topic_id> --no-replies

Best practice:

If a discussion is assignment-linked, assignment search may be more reliable than discussion search.
Use returned discussion_topic_id from assignment results to fetch entries.

Files

canvas files list <course_id>
canvas files list <course_id> --search syllabus
canvas files list <course_id> --search lecture --sort updated_at --order desc
canvas files download <course_id> <file_id>
canvas files download <course_id> <file_id> --force-refresh
canvas files folders <course_id>

Best practice:

Use files download only for Canvas course files with a file_id.
Submission attachments may appear under course submissions; do not assume they are downloadable through files download until a file ID is present.

Grades And Submissions

canvas course grades <course_id>
canvas course submissions <course_id> --student-id self
canvas course submissions <course_id> --assignment <assignment_id> --student-id self
canvas course submissions <course_id> --workflow-state submitted

Best practice:

Use student-id self for the current user.
Non-self submission queries may fail because of Canvas permissions; report permission limits clearly.
For feedback questions, inspect submissions for submission_comments, rubric_assessment, attachments, score, grade, late, and missing.

Course Structure

canvas course overview <course_id>
canvas course syllabus <course_id>
canvas course syllabus <course_id> --no-body
canvas course context <course_id>
canvas course modules <course_id> --items
canvas course modules <course_id> --items --details --search "week 4"
canvas course pages <course_id>
canvas course page <course_id> <page-url-or-id>
canvas course tabs <course_id>
canvas course tab <course_id> modules
canvas course people <course_id> --email

Best practice:

Use course context when broad course context is needed quickly.
Use course syllabus for course policies, grading breakdowns, or syllabus body content.
Use modules for "what do I need to do next?" questions.
Use pages/tabs when the user asks for resources or course navigation content.

To Do And Announcements

canvas announcements --course <course_id>
canvas announcements --course <course_id> --course <other_course_id> --active
canvas todo
canvas todo --course <course_id>

Best practice:

Use todo for the user's current Canvas To Do list and cross-course upcoming work.
Use assignment APIs for full assignment details; todo entries are summaries.

URL Lookup

canvas url "https://school.instructure.com/courses/<course_id>/assignments/<assignment_id>"
canvas url "https://school.instructure.com/courses/<course_id>/files/<file_id>" --no-details

Best practice:

Use URL lookup when the user provides a Canvas URL.
Follow the returned recommended tool when fetch_details is not enough.

Raw Tool Escape Hatch

canvas tool list
canvas tool run <tool_name> --args '{"course_id":"12345"}'

Use this for newly added MCP tools before a first-class CLI command exists.

name	canvas-cli
description	Use the local `canvas` CLI for Canvas LMS workflows. Trigger when you need to find a course, inspect modules/assignments/discussions/files/pages/people/grades/rubrics, or verify Canvas session status from the terminal.

Canvas CLI Agent Instructions

Run commands with the installed canvas executable. Prefer first-class canvas subcommands over raw tool calls. Use uv run canvas only when working inside this repository before installation.

Rules

Resolve a course before using course-scoped commands unless the user provided a course ID.
Use the narrowest first-class CLI command that answers the request.
Use canvas tool run only when no first-class subcommand exists, for debugging, or to mirror MCP tool behavior.
Preserve user privacy: never print cookie values, CSRF tokens, access tokens, or raw auth headers.
Summarize JSON output for the user. Do not paste large raw JSON unless requested.
Include exact IDs when they help the user follow up: course_id, assignment_id, topic_id, file_id.
If no matching Canvas object is found, say that directly and mention the search term/course checked.
If auth fails, run the auth recovery workflow before treating it as a code issue.
Treat quiz support as read-only.

Auth

canvas auth-status
canvas settings profiles
canvas settings choose-profile "<profile-name>"
canvas settings show
canvas settings clear

Use auth-status first when any Canvas command fails unexpectedly.

Auth recovery workflow:

Confirm the user is logged in to Canvas in Chrome, then rerun canvas auth-status.
If multiple Chrome profiles exist, run canvas settings profiles, choose the profile with Canvas cookies, then rerun canvas auth-status.
If the saved profile is stale or wrong, run canvas settings clear, then choose the profile again.
If Canvas host detection is wrong, use CANVAS_BASE_URL=https://school.instructure.com for subsequent commands.
On macOS, Keychain prompts for Chrome cookie access must be approved.

Course Resolution

canvas resolve "ENGL394" --all
canvas courses --all --search ENGL394
canvas tool run resolve_course --args '{"query":"ENGL394","favorites_only":false,"limit":10}'

Best practice:

Prefer canvas resolve for user-provided names like "ENGL394" or "business writing".
Use favorites_only=false when the user expects all active/past courses to be considered.
Confirm the resolved course name when multiple courses could match.

Assignments

canvas assignments list <course_id> --search infographic --limit 20
canvas assignments list <course_id> --bucket upcoming
canvas assignments list <course_id> --search infographic --include-submission
canvas assignments show <course_id> <assignment_id> --include-submission
canvas assignments groups <course_id> --assignments --include-submission

Best practice:

Search assignments by keyword before fetching details when the assignment ID is unknown.
Use assignments show for instructions, due dates, submission settings, discussion links, and attached rubric fields.
Use assignment aliases only as lookup aids; report canonical assignment IDs in final answers.

Rubrics

canvas assignments rubric <course_id> <assignment_id>
canvas assignments rubric <course_id> <assignment_id> --include-assessment

Best practice:

Use assignments rubric when the user asks for grading criteria, rubric categories, points, or how an assignment will be evaluated.
Use --include-assessment only when the user asks how they were graded or wants rubric feedback for their own submission.
Report rubric title, total points, criteria names, point values, and rating levels.
Do not assume use_rubric_for_grading=true; report its value if relevant.
If the assignment has no rubric, say so and suggest checking assignment details/comments instead.

Example workflow:

canvas resolve "ENGL394" --all
canvas assignments list 1402756 --search infographic --limit 20
canvas assignments rubric 1402756 7543238

Discussions

canvas discussion list <course_id>
canvas discussion list <course_id> --search planning
canvas discussion list <course_id> --graded
canvas discussion list <course_id> --search "week 2" --search-in title_or_message
canvas discussion show <course_id> <topic_id>
canvas discussion show <course_id> <topic_id> --no-replies

Best practice:

If a discussion is assignment-linked, assignment search may be more reliable than discussion search.
Use returned discussion_topic_id from assignment results to fetch entries.

Files

canvas files list <course_id>
canvas files list <course_id> --search syllabus
canvas files list <course_id> --search lecture --sort updated_at --order desc
canvas files download <course_id> <file_id>
canvas files download <course_id> <file_id> --force-refresh
canvas files folders <course_id>

Best practice:

Use files download only for Canvas course files with a file_id.
Submission attachments may appear under course submissions; do not assume they are downloadable through files download until a file ID is present.

Grades And Submissions

canvas course grades <course_id>
canvas course submissions <course_id> --student-id self
canvas course submissions <course_id> --assignment <assignment_id> --student-id self
canvas course submissions <course_id> --workflow-state submitted

Best practice:

Use student-id self for the current user.
Non-self submission queries may fail because of Canvas permissions; report permission limits clearly.
For feedback questions, inspect submissions for submission_comments, rubric_assessment, attachments, score, grade, late, and missing.

Course Structure

canvas course overview <course_id>
canvas course syllabus <course_id>
canvas course syllabus <course_id> --no-body
canvas course context <course_id>
canvas course modules <course_id> --items
canvas course modules <course_id> --items --details --search "week 4"
canvas course pages <course_id>
canvas course page <course_id> <page-url-or-id>
canvas course tabs <course_id>
canvas course tab <course_id> modules
canvas course people <course_id> --email

Best practice:

Use course context when broad course context is needed quickly.
Use course syllabus for course policies, grading breakdowns, or syllabus body content.
Use modules for "what do I need to do next?" questions.
Use pages/tabs when the user asks for resources or course navigation content.

To Do And Announcements

canvas announcements --course <course_id>
canvas announcements --course <course_id> --course <other_course_id> --active
canvas todo
canvas todo --course <course_id>

Best practice:

Use todo for the user's current Canvas To Do list and cross-course upcoming work.
Use assignment APIs for full assignment details; todo entries are summaries.

URL Lookup

canvas url "https://school.instructure.com/courses/<course_id>/assignments/<assignment_id>"
canvas url "https://school.instructure.com/courses/<course_id>/files/<file_id>" --no-details

Best practice:

Use URL lookup when the user provides a Canvas URL.
Follow the returned recommended tool when fetch_details is not enough.

Raw Tool Escape Hatch

canvas tool list
canvas tool run <tool_name> --args '{"course_id":"12345"}'

Use this for newly added MCP tools before a first-class CLI command exists.

canvas-cli

Canvas CLI Agent Instructions

Rules

Auth

Course Resolution

Assignments

Rubrics

Discussions

Files

Grades And Submissions

Course Structure

To Do And Announcements

URL Lookup

Raw Tool Escape Hatch

Canvas CLI Agent Instructions

Rules

Auth

Course Resolution

Assignments

Rubrics

Discussions

Files

Grades And Submissions

Course Structure

To Do And Announcements

URL Lookup

Raw Tool Escape Hatch