MechaCat02
359c46afad
The CLI talks only to the Pi's /api surface and holds no Schulcloud credential — only the same bearer token the Claude connector uses. That is not layering for its own sake: a Schulcloud session dies after two hours idle and a CLI process lives for seconds, so a CLI with its own token would be dead most times you reached for it. Routing through the Pi means one session, one keepalive, one monthly cookie paste. sync is a one-way mirror, which follows from the data rather than from scope-cutting: file records are immutable upstream, so there is no versioning, no conflict resolution and no merge. State is keyed by file record id with the path as derived output, so an upstream rename moves the local file instead of duplicating it — verified against the live server. Verification is size-only because the download endpoint exposes no ETag and Schulcloud publishes no hash; size still catches the failure that happens, a truncated download. Downloads land on a .part neighbour and are renamed, so an interrupted run leaves no half-file that a later run mistakes for complete. Deletions are reported but not propagated — a teacher removing a worksheet is no reason to destroy the student's copy — with --prune to opt in. what_changed now clamps to the oldest stored generation instead of refusing, and says it did: "what's new this week" is a reasonable question to ask a two-day-old index. Two build bugs caught by the checks rather than by luck: the smoke harness constructed the app without services, so the index-backed tools were never exercised; and the Docker build could not see scripts/copy-assets.mjs, so the image would have shipped without migrations and silently degraded to live-only. 67 unit tests (9 needing Postgres), smoke green both ways — 34 checks with an index, 32 without, because graceful degradation is a supported mode and not a fallback nobody runs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
4.5 KiB
The schulcloud CLI
Browses and mirrors your Schulcloud files from a laptop, by talking to the schulcloud-mcp server on the Pi.
Why it goes through the Pi
The CLI never talks to Schulcloud. It holds no jwt cookie, no Schulcloud
credential of any kind — only this server's bearer token.
That is not an accident of layering; it solves a real problem. A Schulcloud session dies after two hours of inactivity, and a CLI process lives for seconds, so a CLI with its own token would be dead most times you reached for it. The Pi already keeps one session alive around the clock. Routing through it means one session, one keepalive, and one place to paste a fresh cookie once a month.
It also means the laptop cannot accidentally end the server's session: nothing here can call logout.
Setup
schulcloud login --server https://mcp.example.org --token <MCP_AUTH_TOKEN> --dir ~/Schulcloud
The token is the same MCP_AUTH_TOKEN the Claude connector uses — one token
guards both surfaces. login verifies it before saving, so a typo fails
immediately rather than on first real use. Config is written to
~/.config/schulcloud/config.json with mode 0600.
SCHULCLOUD_SERVER, SCHULCLOUD_TOKEN and SCHULCLOUD_SYNC_DIR override the
file, for CI or one-off invocations.
Commands
schulcloud status how fresh the server's index is
schulcloud ls [--course <id>] [--long]
schulcloud get <fileId> [--out <path>]
schulcloud sync [--dry-run] [--full] [--prune] [--dir <path>] [--jobs <n>]
schulcloud refresh [--course <id>] [--force]
ls --long prints file ids, which is what get takes.
refresh asks the server to re-read Schulcloud. Pass --course when you know
what changed: that is a handful of requests, where a full re-crawl reads every
course. The server refuses a repeat within a minute unless you pass --force.
How sync works
It is a one-way mirror, not a two-way sync, and that follows from the data rather than from laziness: Schulcloud file records are immutable — editing a file upstream produces a new record — so there is no content versioning, no conflict resolution and no merge. "Download what I do not have" is the whole algorithm.
Local state lives in .schulcloud-sync.json at the root of the sync directory,
keyed by file record id with the path as derived output. That is what makes
renames cheap: when a teacher renames a board column, the file moves on disk
instead of being downloaded again under a new name and left duplicated under the
old one.
What it checks, and why only that:
- Size, not a checksum. The download endpoint exposes no
ETagand Schulcloud publishes no hash, so verifying content would mean re-downloading every file to learn what it already told us. Size reliably catches the failure that actually happens — a truncated or interrupted download — and costs astat. - Downloads land on a
.partneighbour and are renamed into place, so an interrupted run never leaves a half-file that a later run mistakes for complete.
Deletions are not propagated by default. A teacher removing a worksheet is
not a reason to destroy your copy of it; sync reports those as "gone upstream,
kept". Pass --prune to actually delete them.
--dry-run prints exactly what would happen, writes nothing, and does not
advance the cursor.
Cursors
The server's sync cursor is a crawl generation id, not a timestamp. This is
deliberate and measured: GET /course-rooms/{id}/board returns the request
time as updatedAt for most elements, so a timestamp cursor would report every
board as changed on every crawl. Comparing generations by identity also detects
deletions, which no timestamp scheme can.
--since on the server API accepts an ISO date for convenience, resolved to the
nearest generation — but correctness never depends on it.
If the server no longer recognises your stored cursor it returns 409 rather
than silently treating everything as new, so you are never tricked into
re-downloading the world. Run sync --full deliberately in that case.
Paths
Mirror paths are Course/Board/Card/filename, built by core/paths.ts.
Every component of that path originates in Schulcloud — course titles, card
titles and filenames are all user-supplied upstream — so each is reduced to a
single safe path component, and the result is re-checked against the sync root
before anything is written. A file named ../../.ssh/authorized_keys cannot
escape, and sync refuses such an entry rather than writing it.