> termcourse: read & post on Discourse instances from the terminal

[merefield (Robert)]

This is a Terminal App (TUI), just a bit of fun … and a bit experimental at this stage!

	Summary	A terminal UI for browsing and posting to Discourse forums with topic lists, full topic views, replies, likes, search, and a built‑in composer.
	Repository Link	GitHub - merefield/termcourse: A terminal based client to access Discourse instances, supporting API keys, username/password (and with MFA token)
	Install Guide	README.md in the repo (Quickstart section)
	Sponsorship	Please consider becoming an ongoing sponsor of my open source work (Sponsor @merefield on GitHub Sponsors · GitHub) at a level that suits your or your organisation’s resources and needs to ensure this project gets the maintenance it deserves and continues to work for your site in the future.

Enjoying termcourse? Please it on GitHub

Overview

> termcourse is a terminal‑based client for Discourse. It behaves like a lightweight browser session with cookie‑based login (username/email + password) and supports TOTP/backup codes for MFA. There’s also an API key fallback for locked‑down or SSO‑only sites.

Features

• Browse Latest / Hot / New / Unread / Top topic lists, with Top period cycling.
• Open topics via arrows + Enter, or number hotkeys (1-0) for the first 10 visible topics.
• View full topics with scrollable posts, sticky header/footer, and a post position/progress bar.
• Expand selected posts to full content; non-selected posts show compact excerpts.
• Reply to entire topics or specific posts.
• Create new topics with title, category picker, and inline body composer.
• Like/unlike posts with per-post visual heart state.
• Search posts and jump directly to the matching topic/post context.
• Inline composer supports cursor movement, insertion, new lines, backspace, and live min-length counter.
• Markdown-aware rendering, including wrapped links and inline image preview support (chafa / viu).
• Emoji substitutions for common :emoji: tokens and :)-style smiles.
• Multi-site credential support via env + per-host credentials.yml (with prompt-for-missing login fields).
• Cookie-session username/password login with MFA support (TOTP + backup code), plus API-key fallback.
• YAML-driven theming with built-ins (default, slate, fairground) and local overrides via theme.yml.
• Reactive resize redraw with configurable poll interval (TERMCOURSE_TICK_MS).
• Optional debug logging for HTTP/auth and UI render diagnostics.

Quickstart

See latest README for more information

git clone https://github.com/merefield/termcourse
cd termcourse
bundle install

Username/password (recommended)

bundle exec bin/termcourse your.discourse.host

API key fallback

DISCOURSE_API_KEY=“your_key” DISCOURSE_API_USERNAME=“your_username” 
bundle exec bin/termcourse your.discourse.host

Auth Notes

• Username/password login uses a normal browser‑style session.
• MFA supported for TOTP and backup codes.
• API keys are supported as a fallback.

Security

• Credentials are not stored; cookies are in‑memory only.
• environment variables or replying to provided prompt avoids passwords in shell history.
• Logging is opt‑in and disabled by default.

Limitations

• Some sites are not compatible with username/password because they forbid scripted remote login flows.
• It lives in the terminal

Credits

Partly inspired by Dumbcourse – Old-browser friendly UI at /dumb (D-pad + small screens)

[merefield (Robert)]

So you can quickly login to multiple sites (obviously one session at a time per tab) I’ve made the following improvements:

termcourse auth and config improvements

• Username/password is now the default login path.
• You don’t need to include https:// anymore - this is optional
• Missing login fields are prompted interactively (for example: username known, password missing).
• CLI help includes core env vars and debug log file locations.

Credentials and ENV behavior

• Supports host-mapped credentials file with lookup order:
  1. TERMCOURSE_CREDENTIALS_FILE (if set)
  2. ./credentials.yml
  3. ~/.config/termcourse/credentials.yml
• Auth precedence:
  1. CLI flags
  2. Host credentials from YAML
  3. Generic DISCOURSE_* env vars
  4. Interactive prompt
• For auth: login, missing username/password values are prompted.
• For API auth, both API username and key must resolve to non-empty values.

Debugging

• HTTP/auth debug: TERMCOURSE_HTTP_DEBUG=1 → /tmp/termcourse_http_debug.txt
• UI render debug: TERMCOURSE_DEBUG=1 → /tmp/termcourse_debug.txt

Repo hygiene

• Added credentials.example.yml and .env.example with aligned examples.
• Added .gitignore entries for local secret files:
  • .env
  • credentials.yml

[merefield (Robert)]

This is pretty low-fi but it works.

You need to have viu or chafa installed - and that can be a project itself

In high quality mode on chafa or with viu, Windows Terminal is superior to MacOS terminal because it supports many more colours (thanks Microsoft!)

Release Notes: Image Rendering (in the terminal!)

Image Rendering

• Added inline post image previews with backend selection:
  • auto tries chafa first, then viu.
  • TERMCOURSE_CHAFA_MODE=stable|quality
  • stable: conservative output for terminal stability.
  • quality: higher-detail/color symbol rendering.
• Added preview height control:
  • TERMCOURSE_IMAGE_LINES (default: 14)
  • Applies to preview line height; useful for tuning visual density.
• Improved viu aspect behavior:
  • Switched to line-targeted rendering (-h) to preserve aspect ratio better.
• Added preview quality filter controls:
  • TERMCOURSE_IMAGE_QUALITY_FILTER=1 filters noisy block-only previews.
  • Set to 0 to always show renderer output.
• Added image download safety limit:
  • TERMCOURSE_IMAGE_MAX_BYTES (default: 5242880)
  • Prevents oversized image downloads from impacting performance.
• Added support for Discourse upload://… image links:
  • Automatically resolves to /uploads/short-url/…
• Improved terminal sanitization/stability:
  • Keeps valid SGR color codes where needed.
  • Strips destabilizing control/graphics sequences.
  • Prevents ANSI escape fragments from being displayed as raw text.

[merefield (Robert)]

A note: I’ve found one site that blocks remote username/password so this client will not work in that situation (unless you own it and can set an API key!)- suggestions welcome, but currently no support in those instances.

[Canapin (Coin-coin le Canapin)]

I’m not sure I’ll use this in the real world, I don’t see the use for me, but I’ve tried it and it’s delightful. I love being able to interact with a next-gen forum platform from a bare-metal, primitive interface.

In some way, it is very aesthetically pleasing.

[merefield (Robert)]

Thank you!

Yeah, I’m thinking it might be useful when:

• you are on a low fi platform
• mucking around on a raspberry pi (not yet tested FYI)
• from a server to check you are up …
• … or if the front end code is crashing!
• for a Discourse site that is very text based …
• … and as a technical curiosity

I’ve been meaning to test it on my phone with Terminus …

[merefield (Robert)]

OK probably last update for today:

• interface is now responsive to window resize
• improvements to content in top bar instructions
• keys 1 to (1)0 now open that number topic on the topic list

Remember to git pull to get updates.

[mcmcclur (Mark McClure)]

Man, now I gotta get to work on my ASCII artwork!!
¯\_(ツ)_/¯

[merefield (Robert)]

I’ve added a fully customisable theming system, this is “fairground”:

… and this is “slate”:

… and this is “rust”:

details in the README

[merefield (Robert)]

ok here we go guys, some juicy updates:

• add support for Private Messages - tap f twice (just list, view and reply at this stage no compose new PM)
• add additional columns for Category, Users, Views, progressively when width expanded
• tweak theming for vertical separators
• updated README

[merefield (Robert)]

I merged this yesterday:

• If you make the effort to install chafa or viu, you will now be rewarded with a new feature: “full window” toggle for post images. On Windows this is particularly good because of the generous colour depth support in Windows Terminal app

[merefield (Robert)]

termcourse now has an unread PM status pop-up in the topic list status bar and just like the browser client will post back read notifications post by post as you move the cursor

[merefield (Robert)]

I’ve merged fixes for themes on macos

[Canapin (Coin-coin le Canapin)]

Nice… Does it run on a Pip-Boy?

[merefield (Robert)]

feel free to PR that or share the colour codes and I’ll add to the example themes yml

[merefield (Robert)]

Love it! Merged, thank you!

Add old school green theme (#1)