CARREL(1)

NAME
carrel - a quiet place to read your markdown

SYNOPSIS
carrel [DIR]
carrel FILE [PATTERN]
cmd | carrel [- [PATTERN]]
carrel --plain FILE [WIDTH]
carrel --plain - [WIDTH]
carrel --render {FILE|-} [WIDTH]
carrel --tasks FILE
carrel [--diff|--no-diff] FILE
carrel --help
carrel --version

DESCRIPTION
carrel is a markdown reader — not an editor, not a workbench, a reading desk.

Run with no arguments it lists the markdown files around you, newest first, with type-to-filter and a directory picker. Given a FILE it opens a reader with vim motions, incremental search that survives reflow and terminal resize, syntax highlighting, tables, images, and mermaid diagrams. Prose is set to a comfortable measure and centred rather than stretched across a wide terminal; tables, code and diagrams still use the full width.

Given a FILE and a PATTERN, it prints matching lines and exits.

Piped input opens the reader too: git show HEAD:README.md | carrel streams the document in as it arrives, so a slow producer paints immediately and your position and search matches hold while content lands. carrel - forces stdin mode; with stdout also piped the document renders as plain text instead, so pipelines pass through.

OPTIONS

--plain
    Render the document as linear plain text on stdout, for screen readers and for pipes. A bare pipe selects this automatically, so carrel doc.md | less does the right thing. Output is ASCII-safe and contains no escape bytes.

--diff
    Read the input as a unified diff even if its name does not say so: a heading per commit and per file, hunks as code. A pipe and a .diff or .patch file are read this way already; a .md file never is.

--no-diff
    Never adapt a diff, even on a pipe.

--render
    Styled linear text for embedding in another tool's output: weight, slant, strike and OSC 8 hyperlinks, but never an SGR colour. With NO_COLOR set it is exactly --plain.

--tasks
    Print every GFM task in the file as checkbox lines and exit. The file is never modified.

--version ,  -V
    Print the version and exit.

--help ,  -h
    Print usage and exit.

KEYS

  Reader

j, k, ↑, ↓
    Scroll by a line.

Ctrl-E, Ctrl-Y
    Scroll by a line, the same as j, k.

Space, b, PgDn, PgUp, Ctrl-F, Ctrl-B
    Page forward and back.

Ctrl-D, Ctrl-U
    Half a page forward and back.

gg, G, Home, End
    Jump to the start or the end.

42G Jump to a row by number.

{ } Move to the previous or next block.

zz zt zb
    Put the current match in the middle, at the top, or at the bottom.

/, ?
    Search forward and backward. Matches survive reflow and resize by construction.

n, N
    Next and previous match.

o   Outline picker.

t   Toggle wide tables between card view and wrapping in place.

r   Toggle rendered blocks — diagrams and math — between art and source.

] [ Move to the next or previous code block. The one in focus is marked in the margin.

X   Jump to the next task-list item, wrapping. A count jumps that many.

y   Copy the focused code block, without its fence. With nothing focused, the nearest code block at or after the top of the screen.

F   Follow a document that is still arriving on a pipe: the view stays at the end as content appears. Any deliberate move away detaches it.

A   Auto-read: the view drifts down a row at a time until any motion stops it.

L   What links here — the documents that link to this one, by [[wikilink]] or by ordinary markdown link. Enter opens one.

l   What this points at — every destination in the document, the mirror of L. Enter opens a local one; an external URL is named, never fetched.

m   Set or clear a bookmark at the current position. Bookmarks are remembered between sessions and survive a resize; they do not survive an edit to the file.

'   Go to the next bookmark, wrapping at the end.

"   List every bookmark with its line; enter jumps to one. (q or Esc closes this pane, and the two link panes below.)

Tab, Shift-Tab
    Select the next or previous link.

Enter
    Follow the selected link.

Ctrl-O
    Go back where you came from.

T   Cycle themes. On an Omarchy desktop the rotation includes omarchy, the palette derived from the theme the rest of the desktop is wearing.

h, F1
    Help.

H   Fold the hint footer.

B   Hide or show the breadcrumb band (the enclosing sections, pinned atop the page while you scroll).

I   Show or hide the document card: words, reading time, structure, links, when the file last changed.

S   Spotlight: dim every paragraph except the one nearest the centre of the view.

za, zM, zR
    Fold the current section behind its heading; fold every section; open all. A <details> block folds the same way behind its summary. Clicking a heading or a summary toggles its fold. Search and links unfold their targets.

%   Jump to the footnote definition of the reference nearest above the view; inside a definition, back to its first reference. Ctrl-O returns.

Esc Clear the selection, the selected link, and any search highlights.

q   Close the file, returning to the home screen if it was opened from there; otherwise quit.

Q, Ctrl-C
    Quit outright, whatever is open.

  Mouse
The reader takes the mouse, so the terminal's own selection is not available while it is up. What replaces it copies the document's text and nothing else: no scrollbar column, no fold markers, no margin outline.

drag
    Select. The selection is copied when the button comes up, so there is no second gesture to remember.

click, double-click, triple-click
    One click sets where a selection starts, two select the word under the pointer, three the whole block. A click that never became a drag lands where it fell: on a heading, or on a <details> summary, it folds that section — the same toggle za gives. Where the margin outline is on, a click in its columns jumps to that section instead of starting a selection.

wheel
    Scroll. Three lines a notch, and more when the notches keep arriving — spin it and the page keeps up, to twelve lines a notch. A pause, or a change of direction, drops straight back to three, so a correction stays precise.

scrollbar
    Dragging the thumb tracks the pointer and keeps hold of the point on the thumb you took it by, so the view does not jump when the hand lands. Clicking the empty track pages one screen toward the click rather than teleporting there.

lamp
    The lamp on the bottom row is a switch: click it to fold the hint footer away, or to bring it back — the same as H.

  Home screen

j, k, ↑, ↓
    Move down and up the list. Ctrl-N/Ctrl-P and Ctrl-J/Ctrl-K do the same while you are typing in the filter, the search or the picker, where the plain letters are part of what you are typing.

gg, G, Home, End
    The first or the last document.

Enter
    Open the selected document.

1, 2, 3
    Continue reading — reopen one of the three most recent documents at the line you left it on.

T   Cycle themes.

H   Hide or show the key hints.

h, F1
    This help. F1 works from any mode; h is a letter, so it only works when you are not typing.

q, Ctrl-C
    Quit.

Esc Clear the filter, then leave it. In the picker it clears the typed path first and closes the picker only when there is nothing left to clear.

i   Filter by name; type to narrow, escape to leave. The match is fuzzy — an in-order subsequence, ranked best-first — as it is in the outline picker.

/   Search inside every file; enter opens at the match.

d   Choose a directory. The input opens on the directory carrel was run from — highlight and all, so enter alone reads where you are — and live and /live both mean a subdirectory of it rather than a path from the filesystem root. A saved root does not change that: the working directory is what d means by "here". Esc clears the input back to empty, which is how an unrelated absolute path is typed and how the remembered places are reached; they lead the empty menu. Typing completes against the filesystem; arrows, Ctrl-J/Ctrl-K or Ctrl-N/Ctrl-P move, enter chooses. Typing owns the letters here, so j and k are part of the path.

Mouse
    Click a file to select it, double-click to open it. The same works in the directory picker, and on the results of a file search.

EXIT STATUS

0   Success. For carrel FILE PATTERN, at least one match.

1   A file that could not be read, an unknown or misplaced option, a [W] argument that is not a column count, or a search that found nothing — so if carrel doc.md pattern; then behaves as it does with grep.

128+N
    Killed by signal N. The terminal is restored first.

-- ends the options, so carrel -- ./-weird.md opens a file whose name begins with a dash. An unknown single-dash flag is ignored when stdin is a pipe, because git hands its pager flags it does not expect to be understood; interactively it is an error.

ENVIRONMENT

NO_COLOR
    Honoured: colours off, weight and emphasis kept.

XDG_CONFIG_HOME, XDG_STATE_HOME, XDG_CACHE_HOME, HOME
    Where the config, the reading positions and the index cache live; see FILES. Each falls back to the usual place under HOME when it is unset or empty.

FILES

$XDG_CONFIG_HOME/carrel/config
    One key = value per line. Carrel writes it itself when you change a setting in the app, and it is safe to edit by hand: unknown keys and # comments are ignored, so a config written for another version still opens. Of a key repeated by hand the FIRST line wins, except place, where every line counts. The eight keys are

    max_width
        The reading measure in columns — prose wraps here and centres on the page. Default 90; 0 turns it off and lets prose fill the terminal. Any other value below 20 is raised to 20, a measure narrower than that being unreadable rather than merely narrow. Tables, code, images and diagrams ignore it and use the full width.

    theme
        The palette, by name: terminal, carrel-dark, carrel-light, catppuccin-mocha, catppuccin-latte, gruvbox-dark, gruvbox-light, tokyo-night, nord, dracula, solarized-dark, solarized-light, everforest, rose-pine, kanagawa, synthwave, oceanic. dark and light are aliases for the two carrel palettes, and omarchy is offered where the desktop publishes one (below). terminal is the default and inherits the terminal's own colours. A name carrel does not know is not an error: it opens on terminal and says so. T cycles them and saves the choice.

    hints
        The lamplight hint row along the bottom. Default true; H toggles it.

    titles
        Show each document's own title on the home screen — title: from its frontmatter, else its first heading — instead of its file name. Default false; a file with neither keeps its name.

    breadcrumb
        The section path pinned atop the page while you scroll, with a rule under it. Default true; B toggles it. A document with no headings never shows one.

    outline_margin
        The section tree pinned in the left margin, the current section lit, on terminals wide enough to spare the columns. Default false, because it moves the text column.

    root
        The directory the home screen lists. d picks one in the app.

    place
        A remembered favourite root, offered by the directory picker. This key repeats, newest first, capped at eight; choosing a root with d records it.

$XDG_STATE_HOME/omarchy/current/theme/colors.toml
    Read, never written. Where Omarchy publishes the active desktop theme as a terminal palette, carrel derives a omarchy palette from it and uses it as the default when no theme is on record. Re-read once a second while that palette is the active one, so omarchy theme set restyles an open reader without a restart; carrel does not read the file at all while you are on a fixed palette.

$XDG_STATE_HOME/carrel
    Two tab-separated files, written atomically so a crash cannot truncate them. positions holds reading positions, so a document reopens where you left it; bookmarks holds the marks m sets. Both keep the 500 most recent documents and drop the oldest beyond that — they are a convenience, not a database. A tab or a newline in a path is escaped, so no filename can corrupt either file.

$XDG_CACHE_HOME/carrel
    The file index: paths and modification times, nothing else. One index-1-hash file per root ever opened, the 32 most recent kept. The 1 is a format version, so a change to the format invalidates the caches deliberately rather than by accident.

PRIVACY
carrel reads only the directory you point it at and sends nothing anywhere. Remote images in documents are never fetched; they render as their alt text.

SEE ALSO
Project home: https://github.com/VaHughes/carrel

LICENSE
MIT OR Apache-2.0, at your option.