canvas-cli

A fast, terminal-first CLI for Canvas LMS.

canvas-cli helps you quickly see assignment work from your shell, with a clean table UI, due-date highlighting, clickable assignment titles, and simple ignore controls.

Features

• Fast assignment listing via Canvas Planner API
• Manual token login flow (canvas login)
• Clean table output with:
  • Colorized courses
  • Overdue due dates highlighted in red
  • Clickable assignment names
• Row-based ignore flow (canvas ignore)
• --all mode to include completed + undated assignments
• Config stored in XDG config directory

Requirements

• Python 3.13+
• uv (recommended)

Installation

Option 1: Install as a global CLI (recommended)

uv tool install --force /path/to/canvas-cli

Then run:

canvas --help

Option 2: Editable install in current environment

uv pip install -e /path/to/canvas-cli

Option 3: Run without installing

uv run canvas --help

Quick Start

1. Log in:

canvas login

You’ll be guided to create a Canvas access token in your browser and paste it securely.

2. View open assignments:

canvas ls

3. Show everything (including completed + undated):

canvas ls --all
# or
canvas ls -a

4. Ignore an assignment by row number:

canvas ignore 4

Or run without args to pick interactively after listing:

canvas ignore

Commands

canvas login

Saves your Canvas base URL + token to local config.

Options:

• --base-url
• --token (optional; if omitted, prompted securely)

canvas ls

Lists assignments from active courses.

Default behavior:

• Shows incomplete assignments with due dates
• Sorted by due date
• Hides ignored assignments

Options:

• --all, -a: include completed and undated assignments

canvas ignore [ROW]

Ignores an assignment so it no longer appears in canvas ls.

• Uses row IDs from the most recent canvas ls output
• If no row is provided, prompts after showing the list

Configuration

Config file location:

• ${XDG_CONFIG_HOME:-~/.config}/canvas-cli/config.json

Stored data includes:

• base_url
• token
• cached display metadata (display_name, host)
• ignored assignment keys
• last ls row mapping (for canvas ignore)

Development

Run lint:

uv run ruff check

Run CLI in dev:

uv run canvas --help

Project Layout

canvas_cli/
  api.py         # Canvas HTTP + endpoint helpers
  cli.py         # Typer commands
  config.py      # config load/save/require
  formatting.py  # due-date + link formatting helpers
  models.py      # dataclasses