BackReference

CLI reference

Every canvas-cli command and flag you can run from your shell.

Commands

Most of canvas-cli happens inside the interactive shell, which you open by running canvas-cli on its own. The commands below handle setup and scripting. For what you type inside the shell, see Slash commands.

Command	Does
`canvas-cli`	Open the interactive shell (runs the sign-in wizard first if nothing is set up)
`canvas-cli login`	Set up your Canvas account and AI provider
`canvas-cli status`	Show what is configured
`canvas-cli ingest <course>`	Download a course into the local cache
`canvas-cli clean`	Delete local data, and optionally your sign-in
`canvas-cli logout`	Remove a profile's stored sign-in
`canvas-cli examples`	Print common workflows

Every command has --help. Run canvas-cli help <command> or canvas-cli <command> --help for the details.

canvas-cli login [--profile <name>]

Walks through your Canvas address, access token, and AI provider (optional; choose Skip to set one up later with /model), verifying the token with Canvas before saving anything. If the profile is already set up, it asks before overwriting. It needs an interactive terminal.

Option	Effect
`--profile <name>`	Set up a separate named profile, such as a second school

See the Quickstart for a walkthrough and Credentials for where everything is stored.

status

canvas-cli status [--profile <name>]

Prints the active profile, Canvas address, whether a token is set, the AI provider and model, the config folder, and where your credentials are stored. It does not contact Canvas, and it always exits 0; use /doctor in the shell to test that the setup actually works.

The AI line shows the provider canvas-cli will actually use. When AI_PROVIDER in your environment overrides the saved one, the line ends in from environment; an unrecognized value is shown as such, with AI off.

	canvas-cli status

	Profile        default
	Canvas URL     https://school.instructure.com
	Access Token   configured
	AI Provider    anthropic (model: claude-opus-5)
	Config Dir     /Users/you/.config/canvas-cli
	Credentials    macOS Keychain

Option	Effect
`--profile <name>`	Inspect a profile other than the active one (default: `CANVAS_CLI_PROFILE`, then `default`)

ingest

canvas-cli ingest [options] <course>

Downloads a course into .canvas-cli/courses/ in the current folder: its structure, documents, and the text of every file. <course> is a course code, a name, or any unique part of either. If it matches more than one course, canvas-cli lists them and stops; if it matches none, it lists your courses with an example and exits with code 1.

Option	Effect
`--json`	Print a JSON summary instead of text, for scripts
`--no-feedback`	Leave out grader comments, feedback files, and rubric scores on your submissions
`--refresh`	Download every file again, even ones already on disk. Without it, a file is only downloaded again when its size on Canvas has changed

canvas-cli ingest ECE216
canvas-cli ingest "Signals and"
canvas-cli ingest ECE216 --json > summary.json

In text mode, progress goes to stderr. With --json, progress is turned off and only the JSON summary goes to stdout, so it pipes cleanly. See Course ingestion for what is captured.

clean

canvas-cli clean [--all] [-y]

Deletes the .canvas-cli folder in the current directory: course caches, workspaces, conversations, exports, and your course list, so you pick courses again next time. It lists what it will remove, with sizes, and asks first.

Option	Effect
`--all`	Also delete every profile's sign-in, including Keychain entries, and the config folder
`-y`, `--yes`	Skip the confirmation

logout

canvas-cli logout [--profile <name>]

Removes a profile’s stored token, AI keys, and settings. Without --profile it removes the active one (CANVAS_CLI_PROFILE, then default). Local course data is untouched; use clean for that.

examples

canvas-cli examples

Prints a short list of common workflows: getting started, using a subscription, ingesting, the interactive shell, profiles, cleaning up, and debugging.

Global Options

Option	Effect
`-V`, `--version`	Print the version
`--debug`	Write diagnostic detail to stderr, with every secret masked. `DEBUG=canvas-cli` does the same
`-h`, `--help`	Show help for canvas-cli or a command

canvas-cli --debug ingest ECE216 2> debug.log

Exit Codes

Code	Meaning
`0`	Success
`1`	Something failed: Canvas rejected the token, the network was unreachable, no course matched, or ingestion failed
`2`	Configuration is missing or inconsistent, for example no Canvas address, or `CANVAS_BASE_URL` set without `CANVAS_ACCESS_TOKEN`
`130`	Cancelled with `Ctrl` `C`

Errors print what went wrong and, on the next line, a suggested fix, such as Run `canvas-cli login` to set up, or set CANVAS_BASE_URL in your environment.