tuipub/README.md

tuipub

A terminal Micropub client for posting notes to your IndieWeb site. It logs in with IndieAuth and is built with Rust and Ratatui. It's developed against StarPunk, but sticks to the spec, so other Micropub servers should work too.

Install

cargo install --path .

Use

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.

Writing (compose screen)

Key	Action
Tab / Shift-Tab	Next / previous field (Title, In reply to, Note, Media, Tags, Crosspost)
Ctrl-T	Post type: Note → Like → Repost (only types the server lists in q=config)
Ctrl-S	Publish or save. The confirm dialog offers d (draft) / p (publish)
Ctrl-P	Your posts
Ctrl-N	New note (asks before discarding changes)
Ctrl-R	Reload crosspost targets from the server
Ctrl-O	Open the last published post
Esc	Quit, or back to the post list while editing (asks if there are unsaved changes)
← → / ↑ ↓, Space, a	Crosspost list: move, toggle, all/none (one row when they fit, stacked when the window is narrow)

Media: Tab to the Media field and press a, then type a path (Tab completes it) or an http(s) URL. You can also paste or drag files onto the field (quoted paths, file:// URIs and \ escapes all work), one per line. Files upload to the server's media endpoint in the background; a URL is attached as is. The file extension decides whether it goes in photo, video or audio. In the field: Enter alt text · d remove · J/K move down/up · ↑↓ select. Publishing waits for uploads to finish. A note with media needs no text, as Micropub doesn't require it. If the server lists post types in q=config and video or audio isn't among them, tuipub warns that it may drop the file.

Key (Media field)	Action
a	Attach a file or URL (Enter on an empty list does the same)
Enter / e	Edit alt text
d / Delete	Remove
J / K	Move down / up (the first one leads)

Likes and reposts (StarPunk 2.5.0+): press Ctrl-T, paste the URL into "Like of" / "Repost of", and optionally add a comment. StarPunk turns likes and reposts of fediverse or Bluesky posts into native favourites/boosts when it crossposts; likes of ordinary web pages aren't crossposted. What a like or repost points at can't be changed afterwards, but its comment can.

When editing, saving sends only the fields you changed. Crosspost targets can't be changed after posting, but StarPunk updates existing crossposts when you edit.

Your posts (Ctrl-P)

Key	Action
↑ ↓ / j k	Move (scrolling past the end loads more). ♥ like · 🔁 repost · ↩ reply
Enter / e	Edit
p	Publish a draft
d	Delete (asks first)
u	Undo the last delete
o	Open in the browser
n	New note
r	Reload
Esc	Back to writing

Ctrl-Q quits from anywhere.

Content is sent as written (Markdown for StarPunk). Tags are comma-separated, and a leading # is dropped. "In reply to" must be an http(s) URL.

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 update delete media. Tokens from older tuipub versions only had create media; run tuipub login again to edit and delete.
• Token storage: the system keyring (Secret Service / gnome-keyring), keyed by your profile URL. Account settings go in ~/.config/tuipub/config.toml.
• Posts list: q=source without url (limit/offset, drafts included). Edits are Micropub update with replace/delete; deletes are delete/undelete; drafts are post-status: draft.
• Media: uploads go to media-endpoint from q=config as multipart/form-data with one file part. The Location of the 201 response is the file's URL, sent as photo ({"value", "alt"} when there's alt text), video or audio. Edits replace a media property that changed and delete one that's now empty. Without a media endpoint you can still attach by URL.
• 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 2.3.3+ stores the Title as the note's # Heading first line. Older versions ignore it, so on those, start the note with # Heading instead.
• Media (2.6.4): only JPEG, PNG, GIF and WebP upload. It keeps the first 4 photos, and video/audio are ignored (its q=config doesn't list them, so tuipub warns). A note needs text even with photos.
• Listing, editing, deleting, drafts and replies need StarPunk 2.4.0+; likes and reposts need 2.5.0+. Ctrl-P shows a message instead of the list when a server says it can't list posts (q in q=config).

Develop

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://.