- Go 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
q quit the whole program from the listing, and it is too easy to type by accident. The frame keymap no longer binds quit: :quit (or :q) is the only way out, and ctrl+c now names that command alone. q still closes a memo, an attachment, an image, the editor and the help panel. The memo tab's q/esc close only led the help line because it took over the frame's q. It now leads because it is close: a window's close action comes right after the frame keys, or it falls past eighty columns. Window keymaps spell it through closeAction, since that rule keys on the name. BREAKING CHANGE: q no longer quits from the listing; type :quit. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
| .claude/rules | ||
| docs | ||
| internal | ||
| .gitignore | ||
| .golangci.yml | ||
| CLAUDE.md | ||
| go.mod | ||
| go.sum | ||
| main.go | ||
| main_test.go | ||
| README.md | ||
memos-tui
A terminal client for Memos, written in Go with Bubble Tea.
It opens on the memos of one account: a listing on the left, a sidebar holding a contribution calendar and the tag tree on the right, and an optional preview of the memo under the cursor. Keys are vim-flavoured, and every one of them is also a typed command.
Features
- Paginated listing, fetching the next page before the cursor reaches the end.
- Sidebar with a calendar heatmap and a folding tag tree, both of which filter the listing.
- Preview of the memo under the cursor, beside the listing or under it.
- Memos opened in tabs of their own, rendered as markdown, with their attachments listed under them: opened with the desktop's own program, downloaded, or read in a tab when they are text.
- Memos edited in place — content, visibility, Space and creation date — and written back to the instance, with what has not been saved refusing to be thrown away.
- First-run setup form: no configuration file has to be written by hand.
- Credentials obtained from an external command, so no token need be stored in clear.
- Fully themable interface — 70 named elements — with a
NO_COLORescape hatch.
Requirements
- Go 1.26 or later to build.
- A Memos instance — 0.30, 0.31, 26.10 or 26.11 — and a personal access
token for it (
memos_pat_…). Which API the instance speaks is asked of it on every connection, so an upgrade needs no change here. xdg-open, to open an attachment with the desktop's own program.- Optionally, a truecolor terminal speaking the kitty graphics protocol, to draw an image attachment in a tab. The terminal is asked, not guessed.
Installation
From a clone:
go build -o memos-tui .
Or, where the module proxy can reach the repository:
go install code.bcarlin.net/labs/memos-tui@latest
First run
Started with no configuration, the program shows a setup form asking for a name, the instance address, an optional user, and a credential. Once the instance accepts it, the configuration file is written and the listing opens.
Nothing is written before the instance has answered, so a configuration that never worked is never saved.
Configuration
The file lives at $XDG_CONFIG_HOME/memos-tui/config.toml, which is
~/.config/memos-tui/config.toml unless the variable says otherwise. It is
created 0600, in a directory created 0700.
download_dir = '~/Downloads'
[[servers]]
name = 'perso'
address = 'https://memos.example.net'
user = 'alice'
token_cmd = ['secret-tool', 'lookup', 'service', 'memos']
token_cmd is an argv — it is executed directly, never through a shell — and
is preferred over token, which stores the credential in clear in the file.
The argv itself is not a secret: it is stored in clear like any other value,
and it is visible in the process table while the command runs, so nothing
secret belongs in its arguments.
The program resolves the command once and reuses what it got. A refusal from
the instance, or a prompt that failed, drops what was held — the next fetch
then resolves again. :reauth re-runs it whatever is held.
Each server has a listing of its own, one tab per [[servers]] entry in the
order of the file. Only the first is fetched at start; another is fetched the
first time gt or gT reaches it, which is when its token_cmd runs. Two
server names that would share a directory on disk — a/b and a_b, .x and
x — are refused, like two equal names.
download_dir is where :download writes when it is given no path. Left out,
it is XDG_DOWNLOAD_DIR — from the environment or from user-dirs.dirs, as
xdg-user-dirs writes it — and then ~/Downloads. It is a top-level key, and
stays above every [section]: written under one, TOML files it there, and it
is silently ignored.
memos-tui --init-config writes a commented file listing every theme setting.
It never touches an existing one.
The program rewrites this file whenever it saves a server, and the rewrite keeps values only: comments are lost, along with any key this version does not know about.
Theming is documented in docs/theme.md.
Usage
memos-tui [options]
-init-config
write a commented configuration file, then exit
-print-theme
list every element of the interface in its style, then exit
If a theme ever leaves the interface unreadable, NO_COLOR=1 memos-tui draws
everything as plain text, whatever the configuration says.
Press ? for the available commands, : to type one, and :quit to leave.
o opens the memo under the cursor in a tab and e edits it, where q closes
that tab; gt and gT walk the tabs.
Documentation
- docs/keymap.md — every binding, by screen and by pane.
- docs/commands.md — every action and what it does.
- docs/theme.md — styles, elements, the colors they take, and the icons.
Development
go test ./...
golangci-lint run
Tests are written first; the conventions and the traps this codebase has run
into are recorded under .claude/rules/.
License
None declared yet.