@lukeguo12210/canvas-cli 0.0.3 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukeguo12210/canvas-cli",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Connect Canvas courses to AI agents: pull modules, files, assignments, pages, folders, and review packs without manual downloads.",
   "type": "module",
   "bin": {

package/scripts/postinstall.mjs

@@ -3,6 +3,10 @@ Canvas CLI installed.
 
 To enable agent skills, run:
 
+  canvas skills install
+
+Or run the installer command directly:
+
   npx skills add lukeguo12210/canvas-cli -g --skill "*" -y
 
 Then authenticate:

package/skills/canvas-shared/SKILL.md

@@ -14,30 +14,39 @@ Read this skill before using any other Canvas skill.
 
 ## CLI Availability
 
-First try:
+Resolve the CLI command once per session:
 
 ```bash
-canvas auth status --format json
+command -v canvas
 ```
 
-If the shell returns `command not found: canvas`, the CLI is not on `PATH`.
+If this succeeds, use plain `canvas ...` commands for the rest of the session.
 
-Use this non-global fallback inside an agent session:
+If this fails, use this non-global fallback prefix for the rest of the session:
 
 ```bash
-npm exec --yes --package @lukeguo12210/canvas-cli -- canvas auth status --format json
+npm exec --yes --package @lukeguo12210/canvas-cli -- canvas
 ```
 
-When using the fallback, replace the leading `canvas` in any command with:
+Do not wrap every command in `canvas ... || npm exec ...`; it is noisy and can make agents wait on npm repeatedly. Pick one command prefix, then run the requested Canvas command once.
+
+Check auth after the command prefix is resolved:
 
 ```bash
-npm exec --yes --package @lukeguo12210/canvas-cli -- canvas
+canvas auth status --format json
+```
+
+or:
+
+```bash
+npm exec --yes --package @lukeguo12210/canvas-cli -- canvas auth status --format json
 ```
 
 For permanent install, tell the user:
 
 ```bash
 npm install -g @lukeguo12210/canvas-cli
+canvas skills install
 ```
 
 If global install fails with `EACCES` under `/usr/local`, do not use `sudo` or create symlinks in `/usr/local`. Ask the user to configure a user-level npm prefix, use a Node version manager, or continue with the `npm exec` fallback for this session.
@@ -48,6 +57,7 @@ Implemented now:
 
 - `canvas auth login`
 - `canvas auth status`
+- `canvas auth schools search <query>`
 - `canvas auth logout`
 - `canvas config show`
 - `canvas me`
@@ -63,6 +73,7 @@ Implemented now:
 - `canvas pages list/show/export`
 - `canvas files list/show/download/download-linked`
 - `canvas folders list/path`
+- `canvas skills install/command/status`
 
 Planned but not implemented yet:
 
@@ -72,8 +83,8 @@ Planned but not implemented yet:
 ## Core Rules
 
 - Use `canvas auth status` first if auth state is uncertain.
-- If no auth config exists, ask the user to run `canvas auth login`.
-- Never print, paste, summarize, or expose a Canvas personal access token.
+- If no auth config exists, use `canvas auth schools search <query>` and then `canvas auth login --school <query> --token-env <env>` or `canvas auth login --school <query> --token <token>` when the user explicitly provides a PAT.
+- Never print, paste, summarize, or expose a Canvas personal access token after receiving it.
 - Default output is JSON and should be preferred for agents.
 - Use `--format pretty` only when presenting a compact human-facing result.
 - Use `--page-all` when completeness matters.
@@ -112,6 +123,8 @@ Do not include those in review packs unless the user explicitly asks.
 
 ```bash
 canvas auth status --format json
+canvas auth schools search "Columbia" --format json
+canvas skills install
 canvas courses list --active --page-all --format json
 canvas courses search "course name" --format json
 canvas courses overview <course-id> --format json

package/skills/canvas-shared/references/auth.md

@@ -4,22 +4,71 @@ Implemented auth commands:
 
 ```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" --format json
 canvas auth status --format json
 canvas auth logout
 canvas config show --format json
 canvas me --format json
 ```
 
-If `canvas` is not on `PATH`, use the npm exec fallback:
+Resolve the CLI command once per session:
+
+```bash
+command -v canvas
+```
+
+If `canvas` is not on `PATH`, use the npm exec fallback prefix for the rest of the session:
 
 ```bash
 npm exec --yes --package @lukeguo12210/canvas-cli -- canvas auth status --format json
 npm exec --yes --package @lukeguo12210/canvas-cli -- canvas auth login
+npm exec --yes --package @lukeguo12210/canvas-cli -- canvas auth login --school "Columbia" --token-env CANVAS_TOKEN
 ```
 
+Do not run repeated compound commands like `canvas ... || npm exec ...`. Pick either `canvas` or the npm exec prefix and use it consistently.
+
 Do not attempt `sudo npm install -g` from inside an agent session. Prefer the fallback above or ask the user to fix their npm global prefix.
 
-## Login Flow
+## Agent Login Flow
+
+Agents can complete login non-interactively when the user explicitly provides a Canvas PAT.
+
+1. Search schools:
+
+```bash
+canvas auth schools search "Columbia" --format json
+```
+
+2. Login with a known school match:
+
+```bash
+canvas auth login --school "Columbia" --token-env CANVAS_TOKEN
+```
+
+or, if the user provides the token directly in chat:
+
+```bash
+canvas auth login --school "Columbia" --token "paste-token-here"
+```
+
+3. For a custom Canvas URL:
+
+```bash
+canvas auth login --school-url https://courseworks2.columbia.edu --school-name "Columbia University (CourseWorks)" --token-env CANVAS_TOKEN
+```
+
+4. Verify:
+
+```bash
+canvas auth status --format json
+canvas courses list --active --page-all --format json
+```
+
+If `--school` matches multiple schools, run `canvas auth schools search <query>` and retry with a more specific value or use `--school-url`.
+
+## Interactive Login Flow
 
 `canvas auth login` is interactive.
 
@@ -40,9 +89,15 @@ Is this your school: Columbia University (CourseWorks) (https://courseworks2.col
 8. Validate token.
 9. Store local config.
 
-## Token Safety
+## Token Handling
+
+The CLI supports agent-provided PATs for initial setup:
+
+- `--token <PAT>`: direct token argument.
+- `--token-env <ENV_NAME>`: read token from an environment variable.
+- `--token-stdin`: read token from stdin.
 
-Never ask the user to paste a token into chat. The token should be pasted into the local terminal prompt from `canvas auth login`.
+Prefer `--token-env` or `--token-stdin` when possible. If the user pastes a PAT into chat, use it only for `canvas auth login`, then do not repeat, print, summarize, or store it anywhere except the Canvas config written by the CLI.
 
 Never print: