moodle-cli 0.6.0 → 0.7.0-alpha.0

package/ONBOARDING.md

@@ -0,0 +1,54 @@
+---
+name: moodle-cli-onboarding
+description: Help a student set up moodle-cli through a short conversation.
+---
+
+# moodle-cli onboarding
+
+You are helping a student connect their university Moodle account to `moodle-cli`. Take ownership of the setup. Keep commands and configuration details out of the conversation unless the student asks or you need their help with an error.
+
+## Start the conversation
+
+Use the student's language and begin with one question:
+
+> What is your university's Moodle URL? You can paste any Moodle page you use, such as the dashboard, a course, or the login page.
+
+Wait for the answer before doing setup work. Do not ask the student to find the site origin, remove part of the URL, choose a runtime, or edit a configuration file.
+
+## Handle the setup
+
+Once the student shares a URL, complete the setup on their computer:
+
+- Check for Node.js 22+ and Bun. Install `moodle-cli` with the runtime available on the computer. Use `bunx --bun moodle-cli` as the command prefix when Bun is the only runtime.
+- Follow redirects and resolve the URL to the final Moodle origin in the form `https://host`. Remove the path, query, and fragment. Confirm that the origin serves Moodle before saving it.
+- Read `~/.config/moodle-cli/config.yaml` if it exists. Set `base_url` to the verified origin and preserve the other settings.
+- Tell the student that Moodle may open in their browser and that you will wait while they complete their university sign-in. Run `moodle auth login`. If a browser opens, let the student finish SSO there, then continue when the command returns.
+- Verify the account with `moodle user --json` and `moodle overview --json`. Diagnose configuration or authentication failures and retry before reporting success. If browser sign-in times out, run `moodle auth login` again after the student is ready.
+- Set up session renewal after verification. On macOS, run `moodle auth keepalive install` and confirm it with `moodle auth keepalive status --json`. On Linux, schedule `moodle auth keepalive --json` every 30 minutes with cron. On other systems, use the operating system scheduler for the same command or explain how to renew with `moodle auth keepalive`.
+- Install the bundled agent skill with `moodle skills add`. In a Bun-only environment, use `bunx --bun skills add https://github.com/bunizao/moodle-cli`.
+
+Do not ask the student to copy a Moodle cookie, `sesskey`, browser database, or API token into the conversation. Do not print credentials. Keep the Moodle session on the student's computer.
+
+## Offer remote access
+
+After local verification succeeds, ask:
+
+> Do you have a Cloudflare account? I can use it to deploy a private remote MCP server, which lets supported web AI clients connect to your Moodle.
+
+If the student declines or has no account, finish the onboarding with local access. Mention that they can add remote access later.
+
+If the student wants remote access, run `moodle mcp deploy`. Let them complete Cloudflare authorization in the browser when Wrangler requests it. The deployment command manages Worker creation, encrypted Moodle session upload, local renewal, and supported client configuration.
+
+Verify the deployment with `moodle mcp status --json`. Continue troubleshooting until the command reports that the Worker and Moodle session are ready. Ask which web AI client the student wants to use, then guide them through that client's current custom MCP connection flow. Put access credentials into the client's connection settings, not the chat.
+
+## Finish with something useful
+
+After both verification commands succeed, run `moodle todo --days 14 --json`. Summarize the student's upcoming work in the language they used.
+
+End with three requests they can try next, adapted to the Moodle data you found:
+
+- “Plan my Moodle work for this week.”
+- “Download the slides from this Moodle link.”
+- “Find forum posts about the next assessment.”
+
+If the student has no upcoming items, say so and use their enrolled units to suggest relevant requests. Report the verified Moodle site and account, but omit session values and internal credentials.

package/README.md

@@ -1,172 +1,214 @@
 # moodle-cli
 
-Terminal-first CLI for Moodle LMS that reuses an authenticated browser session. No Moodle API token required.
+**Give your AI agent access to Moodle.**
 
-## Features
+Let it keep up with deadlines and grades, fetch course files, and search forum discussions. `moodle-cli` finds your active browser session and keeps it alive in the background, so Moodle's login wall stays out of your way.
 
-- Reuses `MoodleSession` from `okta-auth`, your browser, or `MOODLE_SESSION`
-- Uses Moodle AJAX APIs and falls back to authenticated page scraping when needed
-- Lists courses, deadlines, alerts, activities, grades, and forum discussions
-- Agent-friendly JSON/YAML output, field selection, and stable exit codes
+[![npm version](https://img.shields.io/npm/v/moodle-cli?logo=npm)](https://www.npmjs.com/package/moodle-cli)
+[![CI](https://github.com/bunizao/moodle-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/bunizao/moodle-cli/actions/workflows/ci.yml)
+[![Node.js 22+](https://img.shields.io/badge/Node.js-22%2B-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Bun](https://img.shields.io/badge/Bun-supported-fbf0df?logo=bun&logoColor=black)](https://bun.sh/)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-## Install
+## Quick links
 
-```bash
-npm i -g moodle-cli
+- [Set up with your agent](#start-with-your-agent)
+- [Install and sign in manually](#install-and-sign-in-manually)
+- [Study Boooooooooost](#study-boooooooooost)
+- [Connect web AI through a private MCP server](#remote-mcp-for-web-ai)
+- [Developer and agent reference](#for-developers-and-agents)
+
+## For users
+
+### Start with your agent
+
+Paste this into Codex, Claude Code, OpenClaw, Hermes Agent, or another agent that can use your terminal:
+
+```text
+Can you use https://github.com/bunizao/moodle-cli/raw/main/ONBOARDING.md to help me set up moodle-cli?
 ```
 
-Run without installing:
+Your agent asks for your Moodle URL and opens your university's sign-in page when needed. Finish SSO in the browser while the agent waits; it verifies your account and sets up session renewal before reading Moodle. The same onboarding can deploy a private remote MCP server through your Cloudflare account.
+
+### Install and sign in manually
+
+Use Node.js 22+ or Bun:
 
 ```bash
-npx moodle-cli --help
+# npm
+npm install -g moodle-cli
+
+# Bun
+bun add --global moodle-cli
+
+moodle --version
 ```
 
-Standalone binaries are attached to GitHub Releases for macOS arm64 and Linux x64.
+Run without a global install:
 
-### Existing PyPI Users
+```bash
+npx moodle-cli --help
+bunx --bun moodle-cli --help
+```
 
-The TypeScript CLI keeps the same config file and environment variables as the Python package. Migrate with:
+Sign in and open your dashboard:
 
 ```bash
-uv tool uninstall moodle-cli
-npm i -g moodle-cli
+moodle auth login
+moodle overview
 ```
 
-`~/.config/moodle-cli/config.yaml`, `MOODLE_BASE_URL`, and `MOODLE_SESSION` remain compatible.
+On first use, enter your Moodle site origin, such as `https://moodle.example.edu`. `moodle-cli` validates it and saves it to `~/.config/moodle-cli/config.yaml`. If the CLI cannot find an active session, it opens your university's sign-in page and waits for you to finish.
+
+Keep the session active on macOS with `moodle auth keepalive install`. On Linux, schedule `moodle auth keepalive --json` every 30 minutes with cron.
 
-## Authentication
+GitHub Releases also provide standalone binaries for macOS arm64 and Linux x64.
 
-Use one of:
+### Study Boooooooooost
 
-- `okta-auth-cli` configured for your Moodle site
-- an active Moodle browser session
-- a `MOODLE_SESSION` environment variable
+Ask your agent in plain language or run the matching command:
+
+| Student request | CLI command |
+| --- | --- |
+| “Give me a quick Moodle dashboard.” | `moodle overview` |
+| “What is due in the next 14 days?” | `moodle todo --days 14` |
+| “Show my grades and feedback for FIT1045.” | `moodle grades FIT1045` |
+| “Find forum posts about the exam in FIT1045.” | `moodle forums search "exam" --course FIT1045` |
+| “Download the slides from this Moodle link.” | `moodle download '<Moodle URL>' --dest './slides.pdf'` |
 
-Optional Okta setup:
+Unit arguments accept a Moodle course ID or a unique course name.
+
+#### Paste Moodle links directly
+
+The CLI recognizes course, forum, assignment, quiz, resource, page, folder, and grade-report URLs:
 
 ```bash
-npm i -g okta-auth-cli
-okta config
+moodle 'https://moodle.example.edu/course/view.php?id=34637'
+moodle 'https://moodle.example.edu/mod/forum/discuss.php?d=9001#p9101'
+moodle download 'https://moodle.example.edu/mod/resource/view.php?id=91234' --dest './Week 03/slides.pdf'
 ```
 
-On first run, if no `base_url` is configured, the CLI prompts for the Moodle root URL and saves it to `~/.config/moodle-cli/config.yaml`:
+You can paste the same links into your agent and ask it to inspect the page, find related material, or download the file.
 
-```yaml
-base_url: https://school.example.edu
-```
+#### Download course files
 
-Use a root URL only, not `/login/index.php` or `/my/`.
+`moodle download` accepts an activity ID or an authenticated Moodle URL. `--dest` sets the exact local path, and `--force` replaces an existing file after the download completes. Folder activities expose `file_entries` so you can choose which files to save.
 
-### Session Keepalive
+### Remote MCP for web AI
 
-Moodle expires idle sessions server-side, which normally forces a fresh SSO login. The CLI can renew the session in the background instead:
+A private remote MCP server lets a supported web AI client use Moodle when it cannot run the local CLI. You need a Cloudflare account.
 
 ```bash
-moodle auth status               # cache freshness + server session state
-moodle auth keepalive            # renew once; re-login from browser/okta cookies if expired
-moodle auth keepalive install    # macOS launch agent, renews every 30 min
-moodle auth login                # force a fresh login
+moodle mcp deploy
+moodle mcp status
 ```
 
-On Linux, add a cron entry: `*/30 * * * * moodle auth keepalive --json`.
+`moodle mcp deploy` validates Moodle access, deploys a Cloudflare Worker, uploads an encrypted Moodle session, verifies readiness, and installs session renewal. The guided [`ONBOARDING.md`](ONBOARDING.md) asks whether you want this after local setup and helps connect your web AI client.
 
-## Usage
+### Update
 
 ```bash
-moodle --help
-moodle user
-moodle alerts
-moodle todo
-moodle overview
-moodle courses
-moodle grades 34637
-moodle activities 34637
-moodle https://school.example.edu/course/view.php?id=34637
-moodle https://school.example.edu/mod/forum/discuss.php?d=9001#p9101 --json
-moodle skills
-moodle skills generate
-moodle skills add
-moodle update
-moodle update --check-only
+npm install -g moodle-cli@latest
+bun add --global moodle-cli@latest
 ```
 
-Supported Moodle URLs can be passed as the first argument. The CLI routes forum discussion, forum view, assignment, quiz, resource, link, page, folder, course, and grade report URLs to the shortest matching command.
+Standalone binaries print the latest GitHub Release URL instead of modifying themselves.
 
-## Agent Output Contract
+## For developers and agents
 
-JSON-capable commands support:
+### Command and output contract
 
-- `--json`: write JSON to stdout
-- `--yaml`: write YAML to stdout
-- `--table`: force human output
-- `--fields a,b,c`: keep only listed top-level fields; arrays apply the filter per item
+Inspect the full machine-readable command tree:
 
-When stdout is not a TTY, the CLI defaults to JSON. `--table` overrides that.
+```bash
+moodle commands --json
+```
 
-Invalid `--fields` values fail as usage errors and list valid fields.
+Commands support:
 
-With JSON output enabled, errors are one parseable JSON line on stderr:
+- `--json` or `--yaml` for structured output
+- `--table` for human-readable output
+- `--fields a,b,c` to select fields
+- `-o, --output FILE` to write command output or a download receipt
+
+The CLI prints tables in an interactive terminal and JSON when stdout goes to a pipe or file. Structured errors use one JSON object on stderr:
 
 ```json
-{"error":true,"code":"auth_failed","message":"...","hint":"..."}
+{"ok":false,"error":{"code":"auth","message":"...","hint":"..."},"exit_code":3}
 ```
 
-Exit codes:
-
 | Code | Meaning |
 | --- | --- |
 | 0 | Success |
-| 1 | Unexpected error |
-| 2 | Authentication or configuration error |
-| 3 | Usage error |
-| 4 | Requested course, activity, forum, or discussion was not found |
+| 1 | Network, configuration, or unexpected error |
+| 2 | Usage error |
+| 3 | Authentication error |
+| 4 | Course, activity, forum, or discussion not found |
+| 5 | Moodle rejected the request |
 
-## Updates
+### Agent skill
 
-```bash
-moodle update --check-only
-moodle update --json
-```
-
-`moodle update` checks `https://registry.npmjs.org/moodle-cli/latest`. npm installs update with:
+Install the generated skill bundle:
 
 ```bash
-npm install -g moodle-cli@latest
-```
+moodle skills add
 
-Standalone binaries print the latest GitHub Release URL instead of modifying themselves.
+# Direct alternatives
+npx skills add https://github.com/bunizao/moodle-cli
+bunx --bun skills add https://github.com/bunizao/moodle-cli
+```
 
-## Agent Skill
+[`SKILL.md`](SKILL.md) routes agents to focused setup, coursework, forum, download, and maintenance guidance under [`references/`](references/).
 
-Install the bundled agent skill:
+### MCP lifecycle and protocol
 
 ```bash
-npx skills add https://github.com/bunizao/moodle-cli
+moodle mcp deploy
+moodle mcp status
+moodle mcp login
+moodle mcp connect
+moodle mcp remove
+moodle mcp serve
+moodle mcp bridge
 ```
 
-The CLI alias delegates to the same command:
+The default client connection uses `moodle mcp bridge`, which keeps the Bearer token out of client configuration. Use `moodle mcp connect CLIENT --mode remote` for clients that support authenticated remote MCP headers.
 
-```bash
-moodle skills add
-```
+Alpha version `0.7.0-alpha.0` supports MCP `2026-07-28` and a stateless compatibility lane for `2025-11-25` clients.
 
-Regenerate the skill bundle from the command tree and source templates:
+### Configuration
 
-```bash
-npm run build
-npm run skill:generate
-git diff --exit-code -- SKILL.md references agents/openai.yaml
-```
+| Variable | Purpose |
+| --- | --- |
+| `MOODLE_BASE_URL` | Set the Moodle site origin without writing a config file. |
+| `MOODLE_CONFIG` | Use another YAML config file. |
+| `MOODLE_TOKEN` | Provide a `MoodleSession` cookie value in a non-browser environment. |
+| `MOODLE_SESSION` | Compatibility alias for `MOODLE_TOKEN`. |
 
-`SKILL.md` routes agents to focused guidance under `references/`; the exact command and output references remain generated from the CLI.
+For local use, save `base_url` in `~/.config/moodle-cli/config.yaml`. `MOODLE_URL` remains a deprecated fallback for `MOODLE_BASE_URL`.
 
-## Development
+### Build from source
 
-The project typechecks with TypeScript 7 and bundles the Node.js CLI with tsup/esbuild.
+Node.js workflow:
 
 ```bash
-npm install
+npm ci
 npm run check
 npm test
 npm run build
+npm run pack:check
 ```
+
+Bun workflow:
+
+```bash
+bun install
+bunx tsc --noEmit
+bunx vitest run
+bun run build
+bun run pack:check
+```
+
+## License
+
+[MIT](LICENSE)

package/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: moodle-cli
-description: Read Moodle data with the `moodle` CLI. Use for authenticated profile, course discovery, deadlines, alerts, sections, activities, grades, assignment or quiz detail, resources, forum search and discussions, supported Moodle URLs, authentication diagnostics, or CLI updates.
+description: Read Moodle data, download local files, and manage a private Moodle MCP deployment with the `moodle` CLI. Use for authenticated profile, unit discovery, deadlines, alerts, sections, activities, grades, forum workflows, local file downloads, supported Moodle URLs, authentication diagnostics, or MCP deploy, status, login, connection, and removal.
 ---
 
 # Moodle CLI
 
 <!-- Generated by `moodle skills generate`. Edit `src/skill.template.md` and `src/skill-references/`. -->
 
-Use `moodle` for read-only Moodle inspection.
+Use `moodle` for read-only Moodle inspection, explicit local file downloads, and private managed MCP lifecycle operations.
 
 ## Core Steps
 
@@ -15,14 +15,15 @@ Use `moodle` for read-only Moodle inspection.
 2. Run the narrowest command that answers the request. Prefer `--json`; add `--fields` when only a few top-level fields matter.
 3. Parse the result locally and answer with the requested facts, exact dates, and relevant Moodle links. The task is complete when the answer is supported by command output rather than inference.
 
-Resolve an unfamiliar course name with `moodle courses --json` before using a course-specific command. Use `moodle overview --json` only for an explicitly combined snapshot.
+Resolve an unfamiliar unit name with `moodle units --json` before using a unit-specific command. `courses` and `projects` are equivalent aliases. Use `moodle overview --json` only for an explicitly combined snapshot.
 
 ## Branch Map
 
-- **Installation, configuration, authentication failure, or session keepalive**: read [references/setup-and-auth.md](references/setup-and-auth.md).
+- **Installation, configuration, authentication failure, session keepalive, or managed MCP lifecycle**: read [references/setup-and-auth.md](references/setup-and-auth.md).
 - **Profile, course discovery, sections, or activity lists**: read [references/profile-and-courses.md](references/profile-and-courses.md).
 - **Deadlines, todo items, alerts, or a combined snapshot**: read [references/deadlines-and-alerts.md](references/deadlines-and-alerts.md).
 - **Grades or assignment, quiz, resource, link, page, and folder detail**: read [references/coursework-and-grades.md](references/coursework-and-grades.md).
+- **Downloading a resource or selected folder files to local paths**: read [references/downloads.md](references/downloads.md).
 - **Forum discovery, search, discussions, posts, groups, or rendering checks**: read [references/forums.md](references/forums.md).
 - **Output selection, field filtering, error handling, or exit codes**: read [references/output-and-errors.md](references/output-and-errors.md).
 - **Updates, skill installation, or skill regeneration**: read [references/maintenance.md](references/maintenance.md).
@@ -30,7 +31,8 @@ Resolve an unfamiliar course name with `moodle courses --json` before using a co
 
 ## Shared Rules
 
+- Treat `moodle commands --json` as the source of truth for this tool's command tree.
 - Use `--table` only when the user asks for the terminal presentation.
 - Return a concise answer instead of pasting raw output unless raw JSON is requested.
 - Treat `MOODLE_SESSION` as a secret and keep it out of chat, commands shown to the user, and logs.
-- Keep the operation read-only. This CLI inspects Moodle; it does not create or modify Moodle content.
+- Keep remote Moodle data read-only. `moodle download` may write only the explicitly selected local file path; managed MCP commands may change only the selected Worker, local renewal job, client registration, and MCP deployment credentials.

package/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Moodle CLI"
-  short_description: "Inspect courses, grades, deadlines, and forums"
-  default_prompt: "Use $moodle-cli to inspect my Moodle data and answer with the narrowest relevant command."
+  short_description: "Inspect Moodle and download local Moodle files"
+  default_prompt: "Use $moodle-cli to inspect my Moodle data or download selected local Moodle files with the narrowest relevant command."