@lukeguo12210/canvas-cli 0.0.2 → 0.0.4

package/README.md

@@ -2,36 +2,40 @@
 
 [![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-yellow.svg)](LICENSE)
 
-Canvas CLI for technical students and AI agents.
+Connect Canvas courses to AI agents.
 
-`@lukeguo12210/canvas-cli` turns Canvas LMS into a local, scriptable, agent-readable workspace. It is built for students who already live in terminals, editors, notebooks, and AI coding tools. Use the `canvas` command directly, or install the bundled skills so Codex, Claude Code, and other local agents can authenticate, understand your courses, pull materials, inspect upcoming work, and build review packs.
+`@lukeguo12210/canvas-cli` turns Canvas LMS into an agent-readable course workspace. Today, students dig through Canvas, download slides, find assignments, copy pages, and upload everything back into LLMs. Canvas CLI makes that one workflow: pull course materials, modules, files, assignments, pages, folders, and review packs into a structure AI agents can immediately understand.
 
 [Install](#installation--quick-start) · [Agent Skills](#agent-skills) · [Auth](#authentication) · [Commands](#command-system) · [Security](#security--privacy) · [License](#license) · [Roadmap](#roadmap)
 
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=lukeguo12210/canvas-cli&type=Date)](https://www.star-history.com/#lukeguo12210/canvas-cli&Date)
+
 ## Why @lukeguo12210/canvas-cli?
 
-- **Built for technical students** — bring Canvas into your terminal, scripts, and local AI workflow.
+- **Built for technical students** — bring Canvas into your terminal, scripts, and AI workflow.
 - **Agent-native design** — structured skills teach agents Canvas auth, pagination, course structure, and study workflows.
-- **Course context in minutes** — after login, the CLI gathers who you are, what courses you are taking, and where you are in the semester.
-- **Review-pack first** — export modules, pages, assignments, files, discussions, announcements, and calendar context into a structured local course folder.
+- **No more manual Canvas digging** — pull slides, files, pages, assignments, folders, and module structure without download/upload loops.
+- **Review-pack first** — export course structure into an agent-readable folder for study sessions.
 - **Canvas-native commands** — simple commands such as `canvas courses list`, `canvas modules list`, and `canvas review pack`.
-- **Local-first control** — personal access tokens stay local, and course exports are written to directories you choose.
+- **Student-facing scope** — starts with the read-only course surface students need for review, planning, and coursework navigation.
 
 ## Features
 
 | Category | Capabilities |
 | --- | --- |
 | Auth | Interactive `canvas auth login`, school picker, Canvas settings walkthrough, local PAT config |
-| Context | Post-login context bootstrap: user profile, active courses, planner, calendar, upcoming assignments, modules |
 | Courses | List, search, inspect, and summarize active courses |
+| Tabs | Inspect visible Canvas course tabs and external tool links |
 | Modules | Traverse modules and module items in Canvas order |
-| Pages | Fetch pages and export Canvas HTML to Markdown |
+| Pages | List pages, inspect Canvas HTML, and export visible pages |
 | Files | List files/folders and download accessible course files safely |
-| Assignments | List assignments, due dates, descriptions, visible attachments, and assignment groups |
-| Calendar | Pull calendar, planner, and todo context for the semester |
-| Discussions | Inspect discussion prompts and announcements where visible |
-| Review Packs | Preserve Canvas course structure in an agent-readable local export |
-| Agent Skills | Lark-style skills for Codex, Claude Code, and other local agents |
+| Folders | Browse Canvas folder trees and folder paths |
+| Assignments | List assignments, due dates, descriptions, visible attachments, and exports |
+| Raw API | Run read-only `GET` requests against Canvas API paths |
+| Review Packs | Preserve Canvas course structure in an agent-readable export |
+| Agent Skills | Skills that teach agents exact commands, output shapes, and Canvas workflows |
 
 ## Status
 
@@ -52,7 +56,7 @@ Planned next:
 
 - Post-login context bootstrap.
 - Broader review-pack indexing, citations, and linked-file resolution.
-- Grades, submissions, discussions, announcements, calendar, groups, and conversations.
+- Grades, submissions, discussions, announcements, calendar, groups, conversations, and richer review indexing.
 
 ## Installation & Quick Start
 
@@ -74,6 +78,10 @@ npm install -g @lukeguo12210/canvas-cli
 # 1. Authenticate with your Canvas school
 canvas auth login
 
+# Agent/non-interactive auth
+canvas auth schools search "Columbia"
+canvas auth login --school "Columbia" --token-env CANVAS_TOKEN
+
 # 2. List courses
 canvas courses list
 
@@ -133,24 +141,48 @@ canvas review pack --course-id <course-id> --out ./review/<course>
 canvas review pack --course-id <course-id> --out ./review/<course> --include-all-files
 ```
 
-### Domain Commands
+### Full Command Surface
 
 ```bash
+canvas auth login
+canvas auth login --school "Columbia" --token-env CANVAS_TOKEN
+canvas auth login --school-url https://courseworks2.columbia.edu --school-name "Columbia University (CourseWorks)" --token "paste-token-here"
+canvas auth schools search "Columbia"
+canvas auth status
+canvas auth logout
+canvas config show
+canvas me
+
 canvas courses list
 canvas courses search "algorithms"
+canvas courses show <course-id>
+canvas courses overview <course-id>
+canvas tabs list --course-id <course-id>
+
 canvas modules list --course-id <course-id>
 canvas modules items --course-id <course-id> --module-id <module-id>
+canvas modules item --course-id <course-id> --module-id <module-id> --item-id <item-id>
+canvas modules export --course-id <course-id> --module-id <module-id> --out ./module
+
 canvas assignments list --course-id <course-id>
+canvas assignments show --course-id <course-id> --assignment-id <assignment-id>
+canvas assignments export --course-id <course-id> --assignment-id <assignment-id> --out ./assignment
+
 canvas pages list --course-id <course-id>
 canvas pages show --course-id <course-id> --page <url-or-id>
+canvas pages export --course-id <course-id> --page <url-or-id> --out ./page
+
 canvas files list --course-id <course-id>
+canvas files show <file-id>
 canvas files download <file-id> --out ./files
+canvas files download-linked --course-id <course-id> --out ./files
+
 canvas folders list --course-id <course-id>
-```
+canvas folders path --course-id <course-id> --path "course files/week 1"
 
-### Raw Read-Only API
+canvas review pack --course-id <course-id> --out ./review/<course>
+canvas review pack --course-id <course-id> --out ./review/<course> --include-all-files
 
-```bash
 canvas api get /api/v1/courses
 canvas api get /api/v1/courses/<course-id>/modules --params '{"include":["items"]}'
 ```

package/dist/bin/canvas.js

@@ -519,16 +519,112 @@ async function runPostLoginBootstrap() {
   };
 }
 
+// src/commands/shared.ts
+async function activeCanvas() {
+  const profile = await new ConfigStore().activeProfile();
+  return {
+    profile,
+    client: new CanvasClient({
+      baseUrl: profile.baseUrl,
+      token: profile.token
+    })
+  };
+}
+function flagValue(argv, flag) {
+  const index = argv.indexOf(flag);
+  if (index === -1) {
+    return void 0;
+  }
+  return argv[index + 1];
+}
+function requiredFlag(argv, flag, usage) {
+  const value = flagValue(argv, flag);
+  if (!value) {
+    throw new Error(usage);
+  }
+  return value;
+}
+function hasFlag(argv, flag) {
+  return argv.includes(flag);
+}
+function csvFlag(argv, flag) {
+  const raw = flagValue(argv, flag);
+  if (!raw) {
+    return void 0;
+  }
+  const values = raw.split(",").map((value) => value.trim()).filter(Boolean);
+  return values.length > 0 ? values : void 0;
+}
+function pageOptions(argv) {
+  const pageLimitRaw = flagValue(argv, "--page-limit");
+  return {
+    pageAll: hasFlag(argv, "--page-all"),
+    pageLimit: pageLimitRaw ? Number.parseInt(pageLimitRaw, 10) : void 0
+  };
+}
+function positionalArgs(argv) {
+  const valueFlags = /* @__PURE__ */ new Set([
+    "--course-id",
+    "--module-id",
+    "--item-id",
+    "--assignment-id",
+    "--quiz-id",
+    "--topic-id",
+    "--page",
+    "--path",
+    "--out",
+    "--format",
+    "--page-limit",
+    "--page-size",
+    "--page-delay",
+    "--enrollment-state",
+    "--state",
+    "--include",
+    "--params",
+    "--bucket",
+    "--search",
+    "--order-by",
+    "--sort",
+    "--file-id",
+    "--folder-id",
+    "--group-id",
+    "--content-type",
+    "--school",
+    "--school-query",
+    "--school-url",
+    "--url",
+    "--school-name",
+    "--name",
+    "--token",
+    "--token-env"
+  ]);
+  const values = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg.startsWith("--")) {
+      if (valueFlags.has(arg)) {
+        index += 1;
+      }
+      continue;
+    }
+    values.push(arg);
+  }
+  return values;
+}
+
 // src/commands/auth.ts
 var TOKEN_PURPOSE = "Hyperknow";
 async function handleAuthCommand(argv, options) {
   const [subcommand] = argv;
   if (subcommand === "login") {
-    return authLogin(options);
+    return authLogin(argv.slice(1), options);
   }
   if (subcommand === "status") {
     return authStatus(options);
   }
+  if (subcommand === "schools") {
+    return authSchools(argv.slice(1), options);
+  }
   if (subcommand === "logout") {
     return authLogout(options);
   }
@@ -545,16 +641,21 @@ async function handleAuthCommand(argv, options) {
   );
   return 1;
 }
-async function authLogin(options) {
+async function authLogin(argv, options) {
   const io = createPrompt();
   try {
-    const school = await chooseSchool(io);
+    const nonInteractive = hasNonInteractiveLoginArgs(argv);
+    const school = nonInteractive ? resolveSchoolFromArgs(argv) : await chooseSchool(io);
     const settingsUrl = `${school.url}/profile/settings`;
-    process.stdout.write(tokenInstructions(school, settingsUrl));
-    await io.question("Press Enter to open Canvas settings in your browser...");
-    await openBrowser(settingsUrl);
-    process.stdout.write("\nWaiting for your Canvas personal access token.\n");
-    const token = await promptHidden("Paste token: ");
+    const providedToken = await tokenFromArgs(argv);
+    let token = providedToken;
+    if (!token) {
+      process.stdout.write(tokenInstructions(school, settingsUrl));
+      await io.question("Press Enter to open Canvas settings in your browser...");
+      await openBrowser(settingsUrl);
+      process.stdout.write("\nWaiting for your Canvas personal access token.\n");
+      token = await promptHidden("Paste token: ");
+    }
     if (!token) {
       throw new CanvasCliError("EMPTY_TOKEN", "No token entered.");
     }
@@ -588,7 +689,7 @@ async function authLogin(options) {
           },
           user,
           contextBootstrap: bootstrap,
-          next: "canvas context show"
+          next: "canvas courses list --active --page-all"
         },
         meta: {
           command: "auth login"
@@ -604,6 +705,25 @@ async function authLogin(options) {
     io.close();
   }
 }
+async function authSchools(argv, options) {
+  const [subcommand] = argv;
+  const query = subcommand === "search" ? positionalArgs(argv.slice(1)).join(" ") : flagValue(argv, "--query") ?? positionalArgs(argv).join(" ");
+  await writeOutput(
+    {
+      ok: true,
+      data: searchSchools(query).map((school) => ({
+        name: school.name,
+        baseUrl: school.url
+      })),
+      meta: {
+        command: "auth schools",
+        query
+      }
+    },
+    options
+  );
+  return 0;
+}
 async function authStatus(options) {
   const store = new ConfigStore();
   const config = await store.readRedacted();
@@ -694,11 +814,77 @@ async function chooseSchool(io, write = (message) => process.stdout.write(messag
     url: normalizeBaseUrl(school.url)
   };
 }
+function resolveSchoolFromArgs(argv) {
+  const schoolUrl = flagValue(argv, "--school-url") ?? flagValue(argv, "--url");
+  if (schoolUrl) {
+    return makeCustomSchool(flagValue(argv, "--school-name") ?? flagValue(argv, "--name") ?? "Custom Canvas School", schoolUrl);
+  }
+  const schoolQuery = flagValue(argv, "--school") ?? flagValue(argv, "--school-query");
+  if (!schoolQuery) {
+    throw new CanvasCliError(
+      "MISSING_SCHOOL",
+      "Non-interactive auth requires --school <query> or --school-url <url>."
+    );
+  }
+  const matches = searchSchools(schoolQuery, 20);
+  if (matches.length === 0) {
+    throw new CanvasCliError(
+      "SCHOOL_NOT_FOUND",
+      `No Canvas school matched "${schoolQuery}". Use --school-url <url> for a custom Canvas URL.`
+    );
+  }
+  const exact = matches.find((school) => {
+    return school.name.toLowerCase() === schoolQuery.toLowerCase() || school.url.toLowerCase() === schoolQuery.toLowerCase();
+  });
+  if (exact) {
+    return {
+      name: exact.name,
+      url: normalizeBaseUrl(exact.url)
+    };
+  }
+  if (matches.length === 1) {
+    const school = matches[0];
+    return {
+      name: school.name,
+      url: normalizeBaseUrl(school.url)
+    };
+  }
+  throw new CanvasCliError(
+    "AMBIGUOUS_SCHOOL",
+    `Multiple schools matched "${schoolQuery}": ${matches.map((school) => `${school.name} (${school.url})`).join("; ")}. Use a more specific --school value or --school-url.`
+  );
+}
+async function tokenFromArgs(argv) {
+  const directToken = flagValue(argv, "--token");
+  if (directToken) {
+    return directToken.trim();
+  }
+  const envName = flagValue(argv, "--token-env");
+  if (envName) {
+    return process.env[envName]?.trim();
+  }
+  if (argv.includes("--token-stdin")) {
+    return readStdin().then((value) => value.trim());
+  }
+  return void 0;
+}
 async function promptCustomSchool(io) {
   const name = await io.question("School display name: ");
   const url = await io.question("Canvas base URL: ");
   return makeCustomSchool(name, url);
 }
+function hasNonInteractiveLoginArgs(argv) {
+  return Boolean(
+    flagValue(argv, "--school") || flagValue(argv, "--school-query") || flagValue(argv, "--school-url") || flagValue(argv, "--url")
+  );
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
 function tokenInstructions(school, settingsUrl) {
   return `
 Canvas token setup for ${school.name}
@@ -730,91 +916,6 @@ async function validateToken(client) {
   }
 }
 
-// src/commands/shared.ts
-async function activeCanvas() {
-  const profile = await new ConfigStore().activeProfile();
-  return {
-    profile,
-    client: new CanvasClient({
-      baseUrl: profile.baseUrl,
-      token: profile.token
-    })
-  };
-}
-function flagValue(argv, flag) {
-  const index = argv.indexOf(flag);
-  if (index === -1) {
-    return void 0;
-  }
-  return argv[index + 1];
-}
-function requiredFlag(argv, flag, usage) {
-  const value = flagValue(argv, flag);
-  if (!value) {
-    throw new Error(usage);
-  }
-  return value;
-}
-function hasFlag(argv, flag) {
-  return argv.includes(flag);
-}
-function csvFlag(argv, flag) {
-  const raw = flagValue(argv, flag);
-  if (!raw) {
-    return void 0;
-  }
-  const values = raw.split(",").map((value) => value.trim()).filter(Boolean);
-  return values.length > 0 ? values : void 0;
-}
-function pageOptions(argv) {
-  const pageLimitRaw = flagValue(argv, "--page-limit");
-  return {
-    pageAll: hasFlag(argv, "--page-all"),
-    pageLimit: pageLimitRaw ? Number.parseInt(pageLimitRaw, 10) : void 0
-  };
-}
-function positionalArgs(argv) {
-  const valueFlags = /* @__PURE__ */ new Set([
-    "--course-id",
-    "--module-id",
-    "--item-id",
-    "--assignment-id",
-    "--quiz-id",
-    "--topic-id",
-    "--page",
-    "--path",
-    "--out",
-    "--format",
-    "--page-limit",
-    "--page-size",
-    "--page-delay",
-    "--enrollment-state",
-    "--state",
-    "--include",
-    "--params",
-    "--bucket",
-    "--search",
-    "--order-by",
-    "--sort",
-    "--file-id",
-    "--folder-id",
-    "--group-id",
-    "--content-type"
-  ]);
-  const values = [];
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index];
-    if (arg.startsWith("--")) {
-      if (valueFlags.has(arg)) {
-        index += 1;
-      }
-      continue;
-    }
-    values.push(arg);
-  }
-  return values;
-}
-
 // src/commands/api.ts
 async function handleApiCommand(argv, options) {
   const [subcommand] = argv;
@@ -2154,7 +2255,7 @@ async function reviewPack(argv, options) {
 }
 
 // src/bin/canvas.ts
-var VERSION = "0.0.2";
+var VERSION = "0.0.4";
 function helpText() {
   return `canvas \u2014 Canvas LMS CLI for students and agents.
 
@@ -2164,6 +2265,7 @@ USAGE:
 COMMANDS:
   auth login        Interactive Canvas PAT setup
   auth status       Show redacted auth status
+  auth schools      Search supported Canvas school URLs
   auth logout       Remove local Canvas auth config
   config show       Show redacted local config
   me                Show current Canvas user profile