Canvas CLI — Canvas LMS for AI Agents

English | 简体中文

Canvas CLI gives AI agents a controlled interface to Canvas LMS. Agents can inspect courses and assignments, download course files, prepare submissions, work through Classic Quizzes with user-provided answers, and access more than 1,100 Canvas REST API operations.

Commands return structured JSON or YAML. Read operations run directly; writes such as uploads and submissions require --confirm, so an agent can show the exact action before executing it.

Install

Give the repository URL to an agent:

Install Canvas CLI from https://github.com/hhe48203-ctrl/canvas-cli.
Use the Go version declared by the repository, install the canvas binary in a
user-writable directory on PATH, and verify it with canvas --help. Do not use
sudo or change my shell configuration without asking. I will set the Canvas
token myself; do not ask me to paste it into chat.

Or install it manually:

git clone https://github.com/hhe48203-ctrl/canvas-cli.git
cd canvas-cli
go build -o canvas .
mkdir -p "$HOME/.local/bin"
install -m 0755 canvas "$HOME/.local/bin/canvas"

Canvas CLI requires the Go version declared in go.mod.

Configure

Create a Canvas access token in Account → Settings → Approved Integrations, then keep it in an environment variable:

export CANVAS_BASE_URL="https://canvas.example.edu"
export CANVAS_API_TOKEN="your-token"

canvas auth status
canvas auth set-url "https://canvas.example.edu"

CANVAS_API_TOKEN is never written by the CLI. Do not put it in prompts, source files, command arguments, or commits.

Agent Skill

Add a SKILL.md like the following to teach an agent the safe workflow:

---
name: canvas-lms
description: Use Canvas LMS through the canvas CLI for courses, assignments, files, submissions, and quizzes.
---

# Canvas LMS

Use `canvas` instead of browser automation when working with Canvas.

Rules:
- Run `canvas auth status` before the first request.
- Prefer `--json`; use returned IDs instead of guessing them.
- Read assignment or quiz details before preparing an answer.
- Show the target and payload before any write.
- Add `--confirm` only after the user explicitly approves the write.
- Never request or display `CANVAS_API_TOKEN`.

Useful reads:
    canvas courses list --all-pages --json
    canvas assignments list COURSE_ID --all-pages --json
    canvas assignments show COURSE_ID ASSIGNMENT_ID --json
    canvas files list COURSE_ID --all-pages --json

Submission after approval:
    canvas assignments submit COURSE_ID ASSIGNMENT_ID \
      --file answer.pdf --confirm --json

For other endpoints:
    canvas api search KEYWORD
    canvas api describe OPERATION_ID
    canvas api invoke OPERATION_ID --json

Example request:

Find my active biology course, list assignments due this week, and prepare the next submission. Show me the course, assignment, and files before submitting.

Common commands

# Courses and assignments
canvas courses list --all-pages --json
canvas assignments list COURSE_ID --all-pages --json
canvas assignments show COURSE_ID ASSIGNMENT_ID --json

# Files
canvas files list COURSE_ID --all-pages --json
canvas files download FILE_ID --destination ./lecture.pdf

# Text, URL, or multi-file submissions
canvas assignments submit COURSE_ID ASSIGNMENT_ID \
  --text "My response" --confirm --json
canvas assignments submit COURSE_ID ASSIGNMENT_ID \
  --url "https://example.com/work" --confirm --json
canvas assignments submit COURSE_ID ASSIGNMENT_ID \
  --file answer.pdf --file appendix.pdf --confirm --json

# Classic Quizzes
canvas quizzes list COURSE_ID --all-pages --json
canvas quizzes start COURSE_ID QUIZ_ID --confirm --json
canvas quizzes questions SUBMISSION_ID --all-pages --json
canvas quizzes answer SUBMISSION_ID \
  --answers-file answers.json --confirm --json
canvas quizzes complete COURSE_ID QUIZ_ID SUBMISSION_ID \
  --attempt ATTEMPT --validation-token TOKEN --confirm --json

Use canvas --help or canvas <command> --help for all flags and examples.

Full Canvas API

The generated catalog covers more than 1,100 operations from the official Canvas REST API documentation:

canvas api search modules
canvas api describe context_modules_api.create
canvas api invoke courses.list \
  --query enrollment_type=student --all-pages --json
canvas api invoke METHOD /api/v1/example \
  --query key=value --body request.json --confirm --json

api describe shows the method, path, and parameters. api invoke accepts repeatable --path, --query, --header, and --form values, plus --body and --all-pages; write methods require --confirm.

The authoritative API reference is the Instructure Developer Documentation.

Output and safety

• --json and --yaml return stable success or error envelopes.
• --all-pages follows Canvas pagination links without reconstructing them.
• File uploads stream data and complete Canvas' multi-step upload flow.
• Mutating operations require --confirm.
• Quiz answers must come from the user; the CLI does not solve or guess them.
• Canvas permissions and institutional policies still apply.

Development

go test ./...
go build ./...
scripts/update-api-catalog.sh

The script refreshes the embedded catalog from Instructure's official API documentation. See CONTRIBUTING.md for the contribution workflow.

License

MIT