v0.7.2

edstem-cli 0.7.2

--max works again. 0.7.1 renamed it to --limit in a patch release, so scripts that passed --max stopped running. This release puts the old spelling back.

Highlights

• --max is a hidden alias for --limit on edstem threads and edstem activity.

Fixes

• 0.7.1 renamed --max to --limit to match the MCP input name and the sibling CLIs, and listed it as a compatibility note. A breaking rename does not belong in a patch release. --max is accepted again with the same validation, and it is left out of help so new scripts pick up --limit. -n is unchanged.

Everything else from 0.7.1 is unchanged, including the experimental interactive MCP views. See the 0.7.1 notes.

Upgrade

npm install -g edstem-cli@0.7.2

Or, from an earlier release:

edstem update

No configuration or token format changes.

v0.7.1

edstem-cli 0.7.1

Interactive views in the chat, units found by the code you actually type, and tables that fit the terminal. The MCP server can now answer with a small widget instead of a wall of text in hosts that support MCP Apps (Claude, ChatGPT), and hosts that do not still get the same answer as text.

Highlights

• Four interactive views (experimental) — forum catch-up, forum activity, lesson progress and a "Teach me" lesson guide, rendered inside the conversation.
• Units resolve by the code people type — CODE finds the unit Ed stores as CODE 2026 S2, and names match too.
• Tables fit the terminal — list commands show the columns that identify a row and truncate to the terminal width.
• --verbose traces requests — method, URL, status and timing on stderr. Never the token.
• Threads carry read state — an unseen flag and newReplyCount in list output and MCP results.

Interactive views (experimental)

This is an experiment. It ships in edstem-cli first because Ed is a single, well-understood source to try it on. Depending on feedback, the same approach will be extended to the sibling CLIs.

The rule behind every view: a widget stands in for a long list or table the model would otherwise write out, gives it structure, and lets you drill into it in place. Each view is one headline and one main element.

Tool	What you see	What you can do in place
show_forum_catchup	Unread announcements, then threads that are new or have new replies	Open a thread to read its endorsed or first answer; ask for a summary
show_thread_activity	New threads per week, stacked by category	Hover a week for its mix; open it for the most-replied threads; switch to a table
show_lesson_progress	One meter per module, in the order modules opened	Open a module for its unfinished lessons; ask to be taught it or which ones matter
show_lesson_guide	A lesson broken into sections of key points, then practice questions	Step through, answer, see what you got wrong, ask to go over mistakes

A few things are deliberate:

• Stepping, drilling and grading happen in the widget with no model turn. Only "summarise" and "explain" go back to the model, as a normal chat message.
• Practice questions are written by the assistant, and the widget says so. Every question in an Ed lesson quiz is assessed, so the guide never answers, grades or hints at them. It only notes that the lesson's own quiz is still yours to do in Ed.
• The model reads a short text summary, not the widget's data. The widget payload travels in the result's _meta, which ChatGPT and Claude hand to the widget only, so a 12-week activity chart does not cost the model 30KB of context.
• The widget follows the host. Colours, fonts and light or dark mode come from the host, and weeks are bucketed in your own time zone.

Choosing widget or text

Widgets are the default. There are three ways to get text instead:

1. Ask for it. The server's instructions point the model to list_* and read_* for plain text.
2. Use a host without MCP Apps. It receives the text content automatically.
3. Set EDSTEM_WIDGETS=0 on the stdio server to remove the show_* tools entirely.

The teach_lesson MCP prompt starts a lesson guide directly from a course and lesson.

CLI

• Units resolve against the site's own list. A reference is tried in tiers: exact code, the code's leading token, exact name, then a substring of either, so an exact match always wins over a looser one. An unmatched unit is now not_found (exit 4) rather than a usage error, and the message lists your units.
• Tables fit the terminal. List commands declare the few columns that identify a row, and the rest is truncated to the terminal width rather than wrapping to 190 characters. --fields still overrides, and --json still carries every field.
• JSON is compact in a pipe. It is indented only on a terminal.
• --verbose works. It traces each Ed request and its timing to stderr. The token is a header and never appears.
• edstem activity uses the same field names as everything else. It was forwarding Ed's raw response (course_id, created_at); it now projects courseId, createdAt and flattens comments and threads into one row shape.

MCP and skills

• Every tool description is written around intent: what it returns, when to use it, when a sibling fits better, what to call next and what it costs.
• The skill is an intent table: what the user says, and the one command that answers it.
• Shipped text is institution-neutral. No course codes or category names from any one university; a course reference is described as the code exactly as Ed shows it.

Compatibility notes

• --max is now --limit, matching the MCP input name and the sibling CLIs. -n is unchanged. Scripts that pass --max need updating.
• edstem activity output keys changed as described above.
• An unknown unit exits 4 instead of 2.
• MCP clients see four new show_* tools and server instructions. Set EDSTEM_WIDGETS=0 for the previous tool list.

Upgrade

npm install -g edstem-cli@0.7.1

Or, from an earlier release:

edstem update

No configuration or token format changes.

v0.7.0

edstem-cli 0.7.0

• Styles every help page: a wordmark on the root, commands grouped the way gh groups them (core, additional, agent), cyan flags, and a short "Try" list.
• Walks a first run through setup: with no token saved, a terminal session shows where to create one, reads it hidden, checks it with Ed and saves it. A pipe or an agent still gets the auth error.
• Asks instead of failing at a terminal: edstem threads send with no unit opens a picker, and with no body opens $EDITOR. Ambiguous units are chosen from a list.
• Paints tables and mutation plans by role: keys in cyan, what is posted in bold, where it lands in cyan, status-like words toned. --no-color, NO_COLOR, files and pipes stay plain.
• Reads the Ed token through the shared password prompt in edstem auth login.

v0.6.0

edstem-cli 0.6.0

• Adds posting: edstem threads send and edstem replies send write Markdown bodies to Ed, and the MCP tools create_thread and reply_thread stay disabled until EDSTEM_ALLOW_POSTING=1 or the Worker variable MCP_ALLOW_POSTING=1 is set.
• Adds edstem auth login and edstem auth logout, which verify a token before saving it and report its source and path.
• Adds Markdown read verbs for lessons, slides, and threads across the CLI and MCP, plus a consistent slide projection.
• Adds edstem threads search, --offset, and --since, and pages filtered thread listings so --max is honest.
• Adds thread attachments to edstem files list|get and the list_thread_files MCP tool.
• Adds the list_modules tool and triage_unanswered prompt, and makes every MCP tool self-describing.
• Restores edstem update and retries rate-limited reads with backoff. Writes are never retried.
• Fixes unscoped writes: lessons mark-read now needs a query or --all, and submit_slide_answer needs a choice.

edstem slides show now returns the projected slide instead of Ed's raw payload. See CHANGELOG.md for the full list.

v0.5.0

edstem-cli 0.5.0

• Normalizes the CLI around plural nouns, explicit verbs, safe mutation confirmation, and machine-readable command metadata.
• Adds direct course-code resolution with ambiguity protection across CLI and MCP tools.
• Improves lesson and thread filter discovery, normalization, and error reporting.
• Adds safe lesson file and PDF slide listing, MCP resource links, and local downloads.
• Adds a stateless Cloudflare Worker MCP deployment using per-request Bearer or API-key credentials.
• Hardens downloads against redirects, external and lookalike hosts, unsafe filenames, and overwrite collisions.

The legacy singular command grammar has been replaced. Run edstem commands --json for the current command tree.

v0.4.0

edstem-cli 0.4.0

• Rewrites the CLI in TypeScript 7 and publishes it through npm.
• Ships edstem and local stdio edstem-mcp executables from one package.
• Moves the hosted OAuth MCP runtime into the same repository while keeping its Bun and SQLite internals isolated.
• Uses one Ed client, parser, projection, and error model across all adapters.
• Makes compact list projections and --fields the default agent path.
• Preserves Markdown export, quiz submission, lesson progress, remote OAuth security, and reconnect behavior.

v0.3.6

Added

• Added Markdown export for edstem lesson and edstem thread with --md, --format md, and -o <file> support.
• Preserved quiz slide passage text in lesson exports when Ed stores the readable body outside content.

Fixed

• Preserved literal angle brackets in Markdown exports, including comparison text such as x < y and generic-looking text such as Array<T>.

v0.3.5

Highlights

• Switched edstem thread <ref> --json to a compact thread JSON shape that keeps source-grounded reply content while removing redundant structure and surfacing endorsed and staff signals.

Changed

• Compact thread JSON now hoists users, omits default false/zero/empty fields, trims timestamp fractions, and keeps XML content behind --include-html instead of carrying it by default.
• On a corpus of 39 real thread dumps measured with tiktoken o200k_base, compact thread JSON reduced total payload from 74,364 tokens to 28,466 tokens, saving 45,898 tokens overall (-61.72%).
• On the same sample set, the mean savings were 1,176.87 tokens per thread (-55.88% on average), with a median savings of 397 tokens per thread (-54.61%).
• Representative samples from the same corpus ranged from 8,973 -> 2,852 tokens (-68.22%) on a large thread to 518 -> 254 tokens (-50.97%) on a small thread.

v0.3.1

Highlights

• Added edstem update to upgrade the installed CLI in place.

Added

• edstem update now detects common install methods and runs the updater directly.

Changed

• edstem update no longer prints a shell command for manual execution.

Safety

• Source installs are refused by the updater so local checkouts stay local.

v0.2.0

edstem-cli 0.2.0

This release adds lesson support and makes lesson JSON significantly more compact for agent and LLM workflows.

Highlights

• Added lessons and lesson commands for listing course lessons and fetching lesson detail.
• Optimized lesson JSON output by omitting empty, default, and caller-known fields.
• Expanded SKILL.md with explicit lesson lookup workflows for agent usage.

Added

• edstem lessons <course_id> --json
• Lesson filters: --module, --type, --state, --status
• edstem lesson <lesson_id> --json

Changed

• Lesson JSON output is now more compact by default.
• courseId is no longer emitted in lesson JSON output.
• number is omitted when Ed returns the placeholder value -1.
• Empty arrays such as slides: [] are omitted.
• Empty string fields such as outline, dueAt, lockedAt, and updatedAt are omitted.
• Boolean fields that are false by default, such as openableWithoutAttempt, isHidden, isUnlisted, and isTimed, are omitted.

Token savings

On a real edstem lessons 29579 --json sample with 22 lessons, the compact lesson JSON shape reduced payload size from 14,367 to 8,281 characters, which is roughly a 42% reduction in token usage for agent and LLM workflows.

Compatibility note

This release changes the shape of lesson JSON output. Consumers should treat omitted lesson fields as equivalent to empty string, empty list, false, or the placeholder lesson number -1, depending on field type.