tuipub: terminal Micropub client (IndieAuth PKCE login, compose and publish notes)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 19:05:50 -06:00
commit d3ad760798
13 changed files with 6512 additions and 0 deletions
@@ -0,0 +1,61 @@
+# tuipub
+
+A terminal [Micropub](https://micropub.spec.indieweb.org/) client for posting notes to your IndieWeb site.
+It logs in with [IndieAuth](https://indieauth.spec.indieweb.org/) and is built with Rust and [Ratatui](https://ratatui.rs).
+It's developed against StarPunk, but sticks to the spec, so other Micropub servers should work too.
+
+## Install
+
+```sh
+cargo install --path .
+```
+
+## Use
+
+```sh
+tuipub login example.com   # opens your browser to approve access
+tuipub                     # write and publish a note
+tuipub whoami              # show the account and endpoints
+tuipub logout              # revoke the token and forget the account
+```
+
+Running `tuipub` with no account starts the login flow first.
+
+### Keys
+
+| Key | Action |
+| --- | --- |
+| Tab / Shift-Tab | Next / previous field |
+| Ctrl-S | Publish (asks to confirm) |
+| Ctrl-R | Reload crosspost targets from the server |
+| Ctrl-O | Open the last published post |
+| Esc / Ctrl-Q | Quit (asks if there's unpublished text) |
+| ↑ ↓ / j k, Space, a | Crosspost list: move, toggle, all/none |
+
+Content is sent as written (Markdown for StarPunk). Tags are comma-separated, and a leading `#` is dropped.
+
+## How it works
+
+- **Discovery**: reads `rel="micropub"` and `rel="indieauth-metadata"` from your site's `Link` headers and HTML. If there's no metadata link, it falls back to `authorization_endpoint` / `token_endpoint`.
+- **Login**: authorization code flow with PKCE (S256). tuipub runs a one-shot callback server on `127.0.0.1:<random port>` and uses `http://127.0.0.1:<port>/` as its `client_id`. The client ID and redirect URI share an origin, so the server needs no client registration. It checks `state` and `iss`. Scopes requested: `create media`.
+- **Token storage**: the system keyring (Secret Service / gnome-keyring), keyed by your profile URL. Account settings go in `~/.config/tuipub/config.toml`.
+- **Posting**: always sends a JSON body. `mp-syndicate-to` lists exactly the checked targets, and an empty list means "crosspost nowhere". If the target list can't be loaded, `mp-syndicate-to` is left out and the server's default applies (the confirm dialog says so).
+
+### Environment
+
+- `TUIPUB_TOKEN`: use this token instead of the keyring (e.g. one made in StarPunk's `/admin/tokens`).
+- `TUIPUB_CONFIG_DIR`: use a different config directory (handy for dev servers).
+
+## StarPunk notes
+
+- StarPunk takes a note's title from its first line and ignores the Micropub `name` property, so the Title field has no effect there. Start the note with `# Heading` instead.
+- Editing, deleting and listing posts aren't supported yet, because StarPunk's Micropub endpoint doesn't implement `update`, `delete` or `q=source` listing.
+
+## Develop
+
+```sh
+cargo test
+cargo clippy --all-targets -- -D warnings
+```
+
+To try it against a local StarPunk, start it with `DEV_MODE=true`, `SITE_URL`/`ADMIN_ME`/`DEV_ADMIN_ME=http://127.0.0.1:8099/`, then run `TUIPUB_CONFIG_DIR=/tmp/tp tuipub login 127.0.0.1:8099`. Bare `localhost` / `127.*` addresses default to `http://`.