canvas-student-cli

canvas-student-cli is a student-only, read-oriented Canvas LMS command-line tool. It performs authenticated Canvas REST API reads, prints compact JSON success payloads to stdout, and prints compact structured JSON errors to stderr.

The installed executable is canvas-student. The import package is canvas_student_cli.

Install

uv tool install git+https://github.com/soffits/canvas-student-cli.git

For local development:

uv sync --extra dev
uv run canvas-student --version

Configuration

Create a Canvas access token in Canvas account settings. Prefer an owner-readable token file:

mkdir -p "$HOME/.config/canvas-student-cli"
printf '%s\n' 'your_token_here' > "$HOME/.config/canvas-student-cli/token"
chmod 600 "$HOME/.config/canvas-student-cli/token"
export CANVAS_API_TOKEN_FILE="$HOME/.config/canvas-student-cli/token"
export CANVAS_BASE_URL="https://canvas.example.edu"

CANVAS_API_TOKEN is also supported. The base URL must be an HTTPS Canvas origin, with plain HTTP accepted only for localhost tests.

Output

Successful commands preserve the legacy compact JSON stdout format. Errors are compact JSON on stderr with stable categories: usage, config, security, canvas_http, network, and internal.

Commands

Existing read commands are preserved: auth_check, profile, dashboard_cards, todo, upcoming_events, missing_submissions, list_courses, get_course, get_syllabus, list_assignments, get_assignment, list_assignment_groups, get_submission, list_my_submissions, get_submission_feedback, get_grades, list_quizzes, get_quiz, list_files, get_file, list_groups, list_group_members, list_discussions, get_discussion, get_discussion_view, list_announcements, list_modules, get_module, list_module_items, course_structure, list_pages, get_page, calendar_events, list_conversations, get_conversation, conversation_unread_count, list_peer_reviews, get_submission_peer_reviews, user_activity_stream, course_activity_stream, and search_course_content.

Group-scoped reads are also available: get_group, list_group_files, list_group_folders, list_group_discussions, get_group_discussion, get_group_discussion_view, list_group_pages, and get_group_page.

Safe file download:

canvas-student download_file FILE_ID ./file.pdf --max-bytes 50000000
canvas-student download_file FILE_ID ./file.pdf --overwrite

The command first reads Canvas file metadata with bearer authentication, then downloads the Canvas-provided file URL without forwarding Authorization to that file host. It enforces bounded redirects, rejects unsafe local paths, streams to a private temporary file, enforces size limits, fsyncs, and atomically publishes.

Client-Side List Filtering

List commands accept optional projection and filtering after bounded pagination completes:

canvas-student list_assignments 123 --fields id,name,due_at --match lab --sort due_at --descending

--fields keeps comma-separated top-level fields. --match searches scalar top-level values case-insensitively. --sort FIELD sorts by a top-level field. --descending requires --sort. Unknown fields and sort keys fail with deterministic usage errors.

list_conversations also supports --context-code and --query as client-side filters while preserving Canvas --scope and --filter request flags.

Read-Only Guarantees

Authenticated Canvas API requests are structurally constrained to GET. The CLI does not implement Canvas write operations, course audit commands, teacher/admin analytics, or cross-source academic orchestration.

Development

uv sync --extra dev
uv run ruff check .
uv run pytest
uv run python -m build

Project URL: https://github.com/soffits/canvas-student-cli