README
¶
canvas-cli
Agent-friendly CLI for Canvas LMS.
canvas-cli gives students, teachers, scripts, and agents a stable terminal interface for Canvas LMS: predictable commands, JSON output, safe mutation gates, and a raw API escape hatch when the typed command surface is not enough.
Why
Canvas automation often fails because browser flows, ad hoc exports, and one-off scripts are brittle. canvas-cli keeps the common LMS workflows small and scriptable while preserving enough structure for agents to reason about courses, assignments, submissions, files, and inbox state.
Quickstart
Install
Run the following on macOS or Linux:
curl -fsSL https://raw.githubusercontent.com/thedavidweng/canvas-cli/main/install.sh | sh
Run the following on Windows:
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/thedavidweng/canvas-cli/main/install.ps1 | iex"
The installer detects Homebrew automatically and uses it when available (recommended for easy upgrades). Otherwise it downloads the binary to ~/.local/bin.
Other installation methods
Homebrew Cask (macOS/Linux):
brew tap thedavidweng/tap
brew install --cask canvas
Go:
go install github.com/thedavidweng/canvas-cli/cmd/canvas@latest
Manual download: grab the archive for your platform from the latest GitHub Release, extract it, and place the canvas binary on your PATH.
Set up
canvas auth login
The CLI walks you through selecting your Canvas instance and authenticating. You can use an access token (recommended) or a session cookie (experimental, for schools that disable tokens).
Then try it:
canvas courses list
canvas assignments list --course 123 --json
Uninstall
# Homebrew Cask
brew uninstall --cask canvas
# install.sh
curl -fsSL https://raw.githubusercontent.com/thedavidweng/canvas-cli/main/install.sh | sh -s uninstall
# Go
rm "$(go env GOPATH)/bin/canvas"
Remove config if desired: rm -rf ~/.config/canvas-cli
Documentation
- Authentication & Configuration — token, cookie, OAuth, profiles, env vars
- Command Reference — full command inventory with examples
- JSON Contract — envelope schema, exit codes,
--jsonoutput - Safety Model — read-only mode, dry-run, confirm gates
- Architecture — codebase structure and design decisions
- Contributing — development setup and guidelines
Infrastructure
- CI/CD: cli-workflow-template — reusable GitHub Actions workflows
- Docs: site — landing page and documentation
License
Apache License 2.0. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
canvas
command
|
|
|
internal
|
|
|
audit
Package audit provides append-only JSONL audit logging for canvas-cli mutations.
|
Package audit provides append-only JSONL audit logging for canvas-cli mutations. |
|
browsercookie
Package browsercookie extracts browser cookies for Canvas authentication.
|
Package browsercookie extracts browser cookies for Canvas authentication. |
|
canvas
Package canvas defines domain types shared across all canvas-cli packages.
|
Package canvas defines domain types shared across all canvas-cli packages. |
|
cli
Package cli implements all canvas-cli commands using cobra.
|
Package cli implements all canvas-cli commands using cobra. |
|
config
Package config loads, merges, and resolves canvas-cli configuration.
|
Package config loads, merges, and resolves canvas-cli configuration. |
|
output
Package output provides stable JSON envelope construction, JSON serialization, and human-readable table rendering for canvas-cli commands.
|
Package output provides stable JSON envelope construction, JSON serialization, and human-readable table rendering for canvas-cli commands. |
|
testutil
Package testutil provides shared test helpers for canvas-cli.
|
Package testutil provides shared test helpers for canvas-cli. |