CLI Reference¶
Complete documentation for all canvas-ledger commands.
This reference is auto-generated from the CLI source code.
cl¶
canvas-ledger: A local, queryable ledger of Canvas LMS metadata.
Build a durable historical record of your Canvas courses, enrollments, and roles. Answer questions that Canvas itself cannot easily answer:
• What courses have I taught or taken, and when? • What was a student's enrollment history across my courses? • Who was the lead instructor for a co-taught course? • How did enrollment change over time (adds, drops)? • How did a student perform across multiple courses?
Data is stored locally in SQLite. Canvas is read-only—this tool never modifies your Canvas data. You can annotate records with "declared truth" (like who was really the lead instructor) without changing what Canvas reports.
Getting Started: 1. cl config init Configure Canvas URL and API token 2. cl db migrate Initialize the local database 3. cl ingest catalog Fetch all your Canvas courses 4. cl query my-timeline See your involvement history
Usage¶
cl [OPTIONS] COMMAND [ARGS]...
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
-V, --version |
Show version and exit. | No | - |
-v, --verbose |
Enable verbose/debug output. | No | - |
--help |
Show this message and exit. | No | - |
Commands¶
| Name | Description |
|---|---|
config |
Manage canvas-ledger configuration. |
db |
Database operations for canvas-ledger. |
ingest |
Ingest data from Canvas into the local... |
query |
Query the local ledger for historical... |
export |
Export data in JSON or CSV for use by... |
annotate |
Manage annotations (your declared truth vs... |
Sub Commands¶
cl config¶
Manage canvas-ledger configuration.
Configuration is stored in ~/.config/cl/config.toml. API tokens are NEVER stored in the config file—use environment variables or 1Password.
Start here: Run 'cl config init' to set up your Canvas URL and token source.
Usage¶
cl config set [OPTIONS] KEY VALUE
Arguments¶
| Name | Description | Required |
|---|---|---|
KEY |
Configuration key to set. | Yes |
VALUE |
Value to set. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
-u, --canvas-url TEXT |
Canvas base URL (e.g., https://canvas.institution.edu) | No | - |
-d, --db-path PATH |
Path to SQLite database file. | No | - |
-s, --secret-provider TEXT |
Secret provider for API token (env or 1password). | No | - |
-o, --op-reference TEXT |
1Password reference (e.g., op://Dev/Canvas/credential). | No | - |
-f, --force |
Overwrite existing configuration. | No | - |
--help |
Show this message and exit. | No | - |
-r, --reveal |
Show secret provider status (never reveals actual tokens). | No | - |
--help |
Show this message and exit. | No | - |
--help |
Show this message and exit. | No | - |
cl db¶
Database operations for canvas-ledger.
The ledger is stored in a local SQLite database (~/.local/share/cl/ledger.db by default). Run 'cl db migrate' after first install and after updates to ensure the schema is current.
Usage¶
cl db status [OPTIONS]
Arguments¶
No arguments available
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
--no-backup |
Skip automatic backup before migration. | No | - |
--help |
Show this message and exit. | No | - |
--help |
Show this message and exit. | No | - |
cl ingest¶
Ingest data from Canvas into the local ledger.
Ingestion has two levels:
CATALOG 'cl ingest catalog' fetches all courses visible to you—names,
codes, terms, and your role. Fast and safe to run anytime.
OFFERING 'cl ingest offering
All ingestion is read-only and idempotent. Re-running updates records and tracks changes ("drift") over time.
Usage¶
cl ingest status [OPTIONS]
Arguments¶
| Name | Description | Required |
|---|---|---|
OFFERING_ID |
Canvas course ID of the offering to deep ingest. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
-q, --quiet |
Suppress detailed output. | No | - |
--help |
Show this message and exit. | No | - |
-q, --quiet |
Suppress detailed output. | No | - |
--help |
Show this message and exit. | No | - |
-f, --format TEXT |
Output format (table, json). [default: table] | No | - |
--help |
Show this message and exit. | No | - |
cl query¶
Query the local ledger for historical Canvas data. All queries support --format json|csv|table. Data comes from your local ledger—no Canvas API calls.
Usage¶
cl query drift offering [OPTIONS] OFFERING_ID
Arguments¶
| Name | Description | Required |
|---|---|---|
OFFERING_ID |
Canvas course ID of the offering. | Yes |
PERSON_ID |
Canvas user ID of the person. | Yes |
ALIAS_NAME |
Name of the alias to query. | Yes |
PERSON_ID |
Canvas user ID of the person. | Yes |
OFFERING_ID |
Canvas course ID of the offering. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
-f, --format [json|csv|table] |
Output format. [default: table] | No | - |
-t, --term TEXT |
Filter by term name (case-insensitive contains match). | No | - |
-r, --role TEXT |
Filter by role (exact match: teacher, ta, student, etc.). | No | - |
--help |
Show this message and exit. | No | - |
-i, --instructors |
Show instructor responsibility information. | No | - |
-r, --roster |
Show full roster grouped by section (requires deep ingestion). | No | - |
-f, --format [json|csv|table] |
Output format. [default: table] | No | - |
--help |
Show this message and exit. | No | - |
-g, --grades |
Show performance summary (grades only, student enrollments). | No | - |
-a, --alias TEXT |
Filter enrollments to offerings in this alias only. | No | - |
-f, --format [json|csv|table] |
Output format. [default: table] | No | - |
--help |
Show this message and exit. | No | - |
-f, --format [json|csv|table] |
Output format. [default: table] | No | - |
--help |
Show this message and exit. | No | - |
--help |
Show this message and exit. | No | - |
-f, --format [json|csv|table] |
Output format. [default: table] | No | - |
--help |
Show this message and exit. | No | - |
-f, --format [json|csv|table] |
Output format. [default: table] | No | - |
--help |
Show this message and exit. | No | - |
cl export¶
Export data in JSON or CSV for use by other tools. Output goes to stdout for piping to files or other commands.
Usage¶
cl export person [OPTIONS] PERSON_ID
Arguments¶
| Name | Description | Required |
|---|---|---|
OFFERING_ID |
Canvas course ID of the offering. | Yes |
PERSON_ID |
Canvas user ID of the person. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
-f, --format [json|csv] |
Output format. [default: json] | No | - |
--help |
Show this message and exit. | No | - |
-f, --format [json|csv] |
Output format. [default: json] | No | - |
--help |
Show this message and exit. | No | - |
-f, --format [json|csv] |
Output format. [default: json] | No | - |
--help |
Show this message and exit. | No | - |
cl annotate¶
Manage annotations (your declared truth vs Canvas observed truth). Record corrections without changing what Canvas reports—both views are preserved.
Usage¶
cl annotate alias show [OPTIONS] NAME
Arguments¶
| Name | Description | Required |
|---|---|---|
OFFERING_ID |
Canvas course ID of the offering. | Yes |
PERSON_ID |
Canvas user ID of the lead instructor. | Yes |
OFFERING_ID |
Canvas course ID of the offering. | Yes |
CLASSIFICATION |
Involvement classification (e.g., 'developed course'). | Yes |
ANNOTATION_ID |
ID of the annotation to remove. | Yes |
NAME |
Name for the alias (e.g., 'BET 3510'). | Yes |
[OFFERING_IDS]... |
Optional Canvas course IDs to include initially. | No |
NAME |
Name of the existing alias. | Yes |
OFFERING_ID |
Canvas course ID to add to the alias. | Yes |
NAME |
Name of the alias. | Yes |
OFFERING_ID |
Canvas course ID to remove from the alias. | Yes |
NAME |
Name of the alias to delete. | Yes |
NAME |
Name of the alias to show. | Yes |
Options¶
| Name | Description | Required | Default |
|---|---|---|---|
--help |
Show this message and exit. | No | - |
-d, --designation TEXT |
Designation type: 'lead' or 'grade_responsible'. [default: lead] | No | - |
--help |
Show this message and exit. | No | - |
--help |
Show this message and exit. | No | - |
-o, --offering INTEGER |
Filter by Canvas course ID. | No | - |
-f, --format TEXT |
Output format (table, json, csv). [default: table] | No | - |
--help |
Show this message and exit. | No | - |
-t, --type TEXT |
Type of annotation: 'lead_instructor' or 'involvement'. [default: lead_instructor] | No | - |
-y, --force |
Skip confirmation prompt. | No | - |
--help |
Show this message and exit. | No | - |
--help |
Show this message and exit. | No | - |
-d, --description TEXT |
Optional description of the alias. | No | - |
--help |
Show this message and exit. | No | - |
--help |
Show this message and exit. | No | - |
--help |
Show this message and exit. | No | - |
-y, --force |
Skip confirmation prompt. | No | - |
--help |
Show this message and exit. | No | - |
-f, --format TEXT |
Output format (table, json, csv). [default: table] | No | - |
--help |
Show this message and exit. | No | - |
-f, --format TEXT |
Output format (table, json, csv). [default: table] | No | - |
--help |
Show this message and exit. | No | - |