narl-workspace/docs/wiki/Commands.md

<!-- Generated by scripts/wiki.ts from web/src/lib/keymap.ts and web/src/lib/commands.ts. Edit that, then run `make wiki`. -->

# Keys and commands

Everything here is also on `?` (`:help`) inside the app, which draws the same
lists. Keys act on whatever has focus: the row under the cursor in the list, or
the document in the focused tile. Inside the editor the full vim keymap is live,
and `:` opens the command line, where `Tab` completes commands and their
arguments and `↑` / `↓` recall earlier lines.

## Keys

### Browsing and reading

| key | what it does |
| --- | --- |
| `1 … 9 · 0` | switch to that space, like a workspace |
| `Shift 1 … 9` | send the marked nodes, or the selected one, to that space |
| `Tab · Shift-Tab` | next / previous space |
| `w` | overview of every space — hjkl, then Enter |
| `f` | fullscreen the focused pane or tile; again or Esc to leave |
| `Ctrl-h/j/k/l` | focus the tile that way, from the editor too — left of the leftmost is the list; h / l do the same while reading |
| `Ctrl-Shift-h/j/k/l` | move the focused tile that way |
| `L · Shift-Enter` | open the row in a new tile beside the others |
| `gt / gT` | next / previous tile — a view too |
| `j / k · ↓ ↑` | move down / up the list — scroll the document when it has focus |
| `gg / G` | first / last row, or top / bottom of the document — a first g, d, ] or [ waits a second in the status line |
| `Ctrl-D / Ctrl-U` | half a page down / up the open document |
| `zl / zh · zL / zH` | the wide table or code block at the top of the view, sideways — a little, or half its width |
| `]] / \[\[` | next / previous heading of the document — in the editor too |
| `gi` | the info sheet: the open document's headings, earlier versions, backlinks, cards, files and sharing — :share there, Tab between them |
| `gO` | the headings as a list: j/k, Enter jumps there |
| `F` | hints over the links and buttons in view — type one to follow it |
| `gf / gx` | in the editor: follow the link under the cursor / open it in a tab |
| `gx` | open the file under the cursor in a tab of its own |
| `Enter · l` | open a document, or enter a folder — on an open keystore or sealed file, Enter asks for its password |
| `h` | from the document to the list, from the list up a level |
| `o` | new document here, straight into insert mode — when the space has templates, the line offers them first |
| `O` | new folder here |
| `i · a` | edit the open document |
| `R` | rename what is under the cursor — document, folder or card — starting from its name |
| `m / p` | pick nodes up, then drop them all into the folder you walk to |
| `za` | a document's own files, folded open under it in the list — again folds them away; p drops marked files in there |
| `M` | pick up the whole folder — again puts it all back |
| `Ctrl / Shift-click` | pick a row up · every row up to it — drag them onto a folder |
| `S` | the plan screen: the board, the agenda and the calendar, in place of the documents and the list — S again goes back to the documents as they were |
| `t` | agenda — late, due this week, in hand, on every board — on the plan screen |
| `T` | today's diary entry, started if there is none — from templates/day when the diary has one |
| `C` | the diary by month, on the plan screen: h/l a day, j/k a week, H/L a month, . today, Enter opens or starts the day among the documents |
| `[d / ]d` | the diary entry before / after the one open, by date |
| `Ctrl-P` | go to anything by its name, in every space — words before the last narrow the path, as in proj/ingest; Tab or Ctrl-N/P walk, Enter goes |
| `b` | the board, on the plan screen: this space's, or the last one shown — 1 … 9 there shows another's |
| `c` | capture a card into this space's inbox, without leaving here — reading a document, a card about it; Tab on the line makes it a note, or a line in today's entry |
| `Esc · q` | close the document, and its tile when there are several — Esc first puts down what m picked up |
| `/` | full-text search, inside the current space and its text files — Tab takes it to every space, Ctrl-N/P walk the results, Enter opens one |
| `n / N` | next / previous search result, opened beside the results — :noh clears the search |
| `x · dd` | delete what has focus — the row in the list, the document in its pane — into the trash (asks y/N) |
| `u` | undo the last delete: it comes back out of the trash — :trash has the rest |
| `gh` | the open document's earlier versions, as diffs — Enter brings one back |
| `gb` | the documents that link to the open one — \[\[title]] links by title, \[\[ completes one while writing |
| `gc` | the cards about the open document — j/k picks the one :due, :label, Space and H/L act on, Enter turns it over on its board |
| `:` | command line — Tab / Shift-Tab cycle the matches, then the argument; ↑ ↓ recall what ran before |
| `Ctrl-S` | save, from anywhere |
| `?` | this screen — the keys to start with, then on a second ? every key and command; h/l a column, / filters it down |
| `,` | the settings sheet: vim and the clipboard, the vault, the backup, signed-in browsers, ssh keys, capture tokens |
| `q · Esc` | on the plan screen: from a card's back to the board, from the board, the agenda or the calendar back to the documents |

### On a board

The first list is the inbox, the last list is done.

| key | what it does |
| --- | --- |
| `h / l` | to the list left / right — right of the last, to the tile beside |
| `j / k` | down / up the cards |
| `gg / G` | first / last card of the list |
| `J / K` | move the card down / up its list |
| `H / L` | move the card to the list left / right |
| `Space` | into the done list, or back out to the inbox |
| `Enter` | turn the card over, in a tile beside: its labels, description and checklist |
| `gf` | the card's notes — a document, made on first use, opened among the documents; S comes back |
| `o · c` | new card on this list |
| `D` | due date: fri, tm, +3d, 10-31 … |
| `R` | rename the card, or the list when it is empty |
| `z` | show done cards older than a week |
| `F` | a letter over every card in view — type it to put the cursor there |
| `r` | read the board again, for changes made elsewhere |
| `x · dd` | delete the card (asks y/N) |

### On the back of a card

| key | what it does |
| --- | --- |
| `j / k` | down / up the checklist |
| `gg / G` | first / last step |
| `Space · x` | tick the step, or untick it |
| `o` | a new step below the cursor — :task on the line |
| `r` | reword the step |
| `J / K` | move the step down / up |
| `dd` | drop the step |
| `e · i · Enter` | write the description, in the editor — it saves itself, :q or Esc in normal mode leaves |
| `a` | put on a label, or take it off — :label on the line, Tab offers the board's |
| `R · D` | rename the card, its due date |
| `H / L` | send the card to the list left / right |
| `gf` | the card's notes — a document, made on first use, opened among the documents; S comes back |

### In the agenda

| key | what it does |
| --- | --- |
| `j / k` | down / up the cards, then what was written on this day in earlier years, then on to the tile below |
| `h` | to the tile on the left |
| `Enter` | to the card, on its own board beside — or to the entry |
| `Space` | done, where it stands |
| `D` | due date: fri, tm, +3d … — :due on the line |
| `:` | the line, with the agenda kept up — :repeat weekly acts on the card |
| `H / L` | to the list left / right on its board |
| `T` | today's diary entry |

### In the scratchpad

| key | what it does |
| --- | --- |
| `Q` | lower the scratchpad over whatever is on screen, or raise it again — :scratch <text> takes a note without it |
| `Ctrl-Q` | from anywhere, the editor too: the scratchpad down with the last note being written, and again back to where you were, still writing — Firefox quits on it instead |
| `j / k` | down / up the notes, the one touched last on top |
| `o` | a new note, written straight away — it saves itself |
| `Enter · e · i` | write the note — Esc in normal mode, or :q, comes back to the notes |
| `K` | keep the note: a document in the folder being browsed, titled by its first line — :keep <title> names it |
| `C` | make the note a card where :card puts one — the first line its title, the rest its description |
| `A` | put the note at the end of a document — :append, with the one on screen filled in; Tab completes a title |
| `dd` | drop the note (asks y/N) |
| `q · Esc · Q` | raise the scratchpad |

## Commands

A `!` means force, or everything, and nothing else: `:w!` writes over a
newer version, `:search!` looks in every space, `:export!` downloads the
whole workspace. A command that does a second thing takes a word for it:
`:space new <name>`, `:share off`, `:vault unlock`.

### Spaces & folders

| command | what it does |
| --- | --- |
| `:space, :sp [name] \| new <name> \| name <text> \| rm [name]` | switch to a space, or list them — new makes one, name renames the one you are in, rm puts one in the trash with everything in it (asks first) |
| `:mkdir <name>` | make a folder here |
| `:cd <name\|..\|/>` | enter a folder, .. goes up, / back to the space |
| `:import, :imp [zip [/]]` | upload a folder into this one — markdown becomes documents, links follow; zip takes loose files or a .zip instead, and zip / pours an :export! back in, spaces and boards and all |
| `:move, :mv <folder\|..\|/>` | move the marked nodes, or else the selected one, into a folder here, up one level, or to the root of the space |
| `:trash [purge]` | what was deleted — j/k, Enter brings it back, x deletes it for good; :trash purge empties it |

### Boards

| command | what it does |
| --- | --- |
| `:board` | this space's board, on the plan screen — the last one shown when this space has none |
| `:plan, :special` | the plan screen: the board, the agenda and the calendar, in place of the documents — S goes there and back again; 1 … 9 on the board picks the board |
| `:card, :c [title]` | add a card — reading a document, one about it, titled after it unless named, and gf on it comes back; on the board to the list under the cursor, elsewhere to this space's inbox |
| `:due <when\|->` | due date of the card in focus — on the board, its back, in the agenda, or the open document's: today, tm, fri, +3d, +2w, 10-31, 2026-10-31 — - clears |
| `:repeat <rule\|->` | once the card is done, a copy comes back in the inbox: daily, weekly, monthly, yearly, +3d, +2w, +6m — - stops it |
| `:done` | move the card in focus into the done list, or back out to the inbox |
| `:task, :step [add] <text> \| edit <text>` | add a step to the open card's checklist, below the cursor — edit rewords the step under it; add is only needed for a step that starts with edit |
| `:label <name>` | put a label on the card, or take it off when it has it — each name keeps its colour everywhere |
| `:list <name> \| name <text> \| rm` | add a column to the board — name renames the one under the cursor, rm deletes it and every card on it (asks first) |
| `:agenda, :ag` | what is late, due this week, or in hand — across every board |

### Documents

| command | what it does |
| --- | --- |
| `:scratch, :sc [text]` | the scratchpad, lowered over whatever is on screen — Q does the same; with text, a note on it without leaving |
| `:append [document]` | put the scratch note at the end of a document, by its title — Tab completes it — or the one on screen, and take it off the scratchpad |
| `:keep [title]` | make the scratch note a document in the folder being browsed — titled by its first line unless given one — and take it off the scratchpad |
| `:new, :n, :o [template] [yyyy-mm-dd] [name]` | start a new document here — from one of the space's templates, dated, named; in the diary from templates/day |
| `:cal, :calendar` | the diary by month — h/l a day, j/k a week, H/L a month, Enter opens the day or starts it |
| `:today [text]` | open today's diary entry, starting one if there is none yet; with text, a timed line at its end without going there |
| `:next` | open the next node down the list |
| `:prev` | open the previous node |
| `:first` | open the first node in the list |
| `:last` | open the last node in the list |
| `:random` | open something here at random — good for re-reading |
| `:delete, :d, :rm [id]` | delete a node, and everything under it, into the trash (asks first) — u brings it back |
| `:history, :hist` | the open document's earlier versions as diffs — j/k, Enter brings one back (gh) |
| `:backlinks, :bl` | the documents that link to the open one — j/k, Enter opens one (gb) |
| `:cards` | the cards about the open document — its own, and the ones whose summary links here: j/k picks the one :due, :label, Space and H/L act on, Enter turns it over on its board (gc) |
| `:source` | show an open markdown file as written, or rendered again |
| `:outline, :toc` | the open document's headings to pick from — gO, in the editor too |
| `:info [outline\|history\|backlinks\|cards\|files\|share]` | what is known about the open document: its headings, earlier versions, backlinks, cards, files and sharing — Tab between them (gi) |
| `:search, :se [text]` | full-text search in this space (empty clears) |
| `:search!` | full-text search across every space — `/` then Tab |
| `:noh, :nohlsearch` | clear the search filter |
| `:reload, :r` | re-read the current folder from the server |

### Tiles

| command | what it does |
| --- | --- |
| `:close, :clo` | close the focused tile — q while reading; on the plan screen, back to the documents; asks when its draft could not be written |
| `:only, :on` | close every tile but the focused one |
| `:ls, :buffers, :files` | list the open tiles, % on the focused one |
| `:buffer, :b <n\|name>` | focus a tile by its number in :ls, or by the start of its name |
| `:bnext, :bn` | the next tile — gt |
| `:bprevious, :bp, :bN` | the previous tile — gT |

### Writing

| command | what it does |
| --- | --- |
| `:write, :w` | save what is being written — the open document, a card's description, a note — rather than in a moment |
| `:write!` | save even over a newer version saved somewhere else since this one was opened |
| `:wq, :x` | leave the editor with everything written, as :q does |
| `:wq!` | save over a newer version, as :w! does, and leave the editor |
| `:quit, :q` | leave the editor with what is waiting written first, or close the document when already reading |
| `:quit!` | leave the editor, letting go of what is not saved yet |
| `:edit, :e [id]` | edit the open document, or open a node by id |
| `:edit!` | throw away the draft and re-read the document from the server |
| `:name, :title, :rename <text>` | rename what has focus — document, folder, file, or card on a board; bare, while writing, into the title — :space name and :list name rename those |
| `:date <yyyy-mm-dd>` | re-date the open document |
| `:upload, :up [seal]` | files for the open document — while writing, embedded at the cursor — or, from the list, into this folder; seal puts them into this folder sealed in the vault, encrypted before they touch the disk |

### Sharing & export

| command | what it does |
| --- | --- |
| `:share [off\|new]` | publish the document behind an unguessable link and copy it — off takes it back, new mints a fresh link and the old one stops working; both ask first, and :info share shows where it stands |
| `:copy, :yank` | copy the whole document to the clipboard as markdown |
| `:export, :exp` | download what has focus — the file under the cursor as it is, a document as a .md file with what is typed so far |
| `:export!` | download the whole workspace — every space, document and file — as a zip |

### Vault

| command | what it does |
| --- | --- |
| `:vault [unlock\|lock\|passwd]` | the vault in the settings sheet, or, the first time, set its password — unlock opens it, lock closes it now, passwd changes the password and re-seals every file under a new key |
| `:encrypt, :seal` | seal the file under the cursor in the vault — a folder stays sealed: every file in it, and every file added later |
| `:decrypt, :unseal` | take the file under the cursor back out of the vault — on a sealed folder, unseal it and every file inside |

### Settings & session

| command | what it does |
| --- | --- |
| `:stats` | word, line and node counts |
| `:set [option]` | vim, novim, clipboard, noclipboard, board, noboard — bare, the settings sheet |
| `:backup [login <proton-username> \| logout]` | the proton drive mirror, in the settings sheet — login sets it up, logout forgets its session |
| `:backup!` | back up to proton drive now, rather than when the workspace falls quiet |
| `:sessions [rm <n>]` | every browser signed in, in the settings sheet — rm signs the n-th out, and locks the vault |
| `:sshkey [add <name> <key> \| rm <name> \| vault <name> on\|off]` | the keys allowed to mount the workspace over sftp, in the settings sheet — add, rm, and vault on\|off for which may read sealed files |
| `:token [add <name> \| rm <name>]` | the tokens that capture into the workspace from outside it, in the settings sheet — add shows a new one once and copies it, rm retires one |
| `:help, :h [all]` | the keys to start with — ? again, or :help all, for every key and command |
| `:settings [options\|vault\|backup\|sessions\|keys\|tokens]` | the settings sheet: vim and the clipboard, the vault, the backup, the browsers signed in, ssh keys and capture tokens — Tab between them (,) |
| `:logout` | end the session |
| `:logout!` | end every session, on every device — for a lost phone or a shared computer |

### Old spellings

These still work for one release, and run as the line beside them. Help and
`Tab` no longer offer them.

| was | now |
| --- | --- |
| `:space!` | `:space new` |
| `:rmspace` | `:space rm` |
| `:rms` | `:space rm` |
| `:list!` | `:list rm` |
| `:task!` | `:task edit` |
| `:upload!` | `:upload seal` |
| `:import!` | `:import zip` |
| `:unshare` | `:share off` |
| `:link` | `:share new` |
| `:clear` | `:noh` |
| `:download` | `:export` |
| `:dl` | `:export` |
| `:unlock` | `:vault unlock` |
| `:lock` | `:vault lock` |
| `:passwd` | `:vault passwd` |
| `:name!` | `:list name` on the board, `:space name` elsewhere |
| `:card!` | `:card` while reading the document |
| `:unmark` | `Esc` in the list |