tuxedo

https://github.com/webstonehq/tuxedo
Admin
tuxedo is a fast, keyboard-driven terminal UI and CLI for todo.txt featuring Vim-style keybindings,...
Tokens:10,317
Snippets:73
Trust Score:8.5
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Install a custom theme with curl

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Creates the tuxedo themes directory and downloads the gruvbox-dark-soft.toml theme from the official repository. After copying a theme file into ~/.config/tuxedo/themes/, press T in tuxedo to pick it.

```sh
mkdir -p ~/.config/tuxedo/themes
curl -o ~/.config/tuxedo/themes/gruvbox-dark-soft.toml \
  https://raw.githubusercontent.com/webstonehq/tuxedo/main/docs/themes/gruvbox-dark-soft.toml
```

--------------------------------

### tuxedo command-line usage examples

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Shows common tuxedo invocations: launching the TUI, opening the sample file, running CLI commands, updating, and showing help/version.

```sh
tuxedo [FILE]      # launch the TUI on FILE (created if missing)
tuxedo             # TUI on the default file (see resolution below)
tuxedo --sample    # open the bundled sample file in the temp dir
tuxedo <command>   # run a one-shot CLI command — see "Command-line interface"
tuxedo update      # print upgrade instructions for your install
tuxedo --help
tuxedo --version
```

--------------------------------

### Install tuxedo from source with cargo

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Installs the latest tuxedo from the Git repository using Cargo.

```sh
cargo install --git https://github.com/webstonehq/tuxedo
```

--------------------------------

### Normal-mode keybindings configuration (keybinds.toml)

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Complete example of the [normal] table in keybinds.toml, listing every rebindable action with its default key or array of alternatives. Copy it, change the keys you care about, and delete the rest; anything left out keeps its default. Note that begin_prompt_project defaults to '+' which cannot be written here because the parser reads '+' as a modifier separator, and cycle_theme has no default.

```toml
[normal]

# Navigation
cursor_down    = ["j", "Down"]
cursor_up      = ["k", "Up"]
cursor_top     = "gg"
cursor_bottom  = "G"
half_page_down = "Ctrl-d"
half_page_up   = "Ctrl-u"

# Editing
begin_add            = "n"
begin_edit           = "e"
begin_edit_insert    = "i"
toggle_complete      = "x"
delete               = "dd"
reschedule           = "r"
cycle_priority       = "p"
move_task_down       = "J"
move_task_up         = "K"
begin_prompt_context = "c"
copy_line            = "yy"
copy_body            = "yb"
undo                 = "u"
# begin_prompt_project defaults to "+", which can't be written here (the
# parser reads "+" as a modifier separator). Pick another key to move it, e.g.
# begin_prompt_project = "P"

# Filtering, sort, view
begin_search        = "/"
arm_f               = "f"        # leader for the fp / fc / ff / fs chords
pick_project        = "fp"
pick_context        = "fc"
pick_saved_filter   = "ff"
save_current_filter = "fs"
cycle_sort          = "S"
toggle_visual       = "v"
toggle_selected     = "space"
go_list             = "l"
toggle_archive_view = "a"
archive_completed   = "A"
toggle_show_done    = "H"
toggle_show_future  = "F"

# Layout & theme
toggle_left_pane  = "["
toggle_right_pane = "]"
open_theme_picker = "T"
cycle_density     = "D"
toggle_line_num   = "L"
# cycle_theme has no default — bind a key to cycle themes without the picker:
# cycle_theme = "Ctrl-t"

# System
open_command_palette = [":", "Ctrl-P"]
open_share           = "s"
open_help            = "?"
open_settings        = ","
escape_stack         = "Esc"
quit                 = "q"

```

--------------------------------

### tuxedo CLI usage examples

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Shows common tuxedo commands for adding, listing, completing, prioritizing, archiving, and outputting tasks as JSON. The commands mirror todo.txt-cli and support aliases.

```sh
tuxedo add "Pay rent +home @bank due:2026-07-01"   # or: tuxedo a "..."
tuxedo ls @bank                                     # filter by context
tuxedo do 3                                          # mark task 3 complete
tuxedo pri 3 A                                        # set priority
tuxedo archive                                        # move done tasks to done.txt
tuxedo ls --json | jq .                              # machine-readable output
```

--------------------------------

### Install tuxedo with Homebrew

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Install tuxedo on macOS using the Homebrew package manager. Run this command in a terminal to install the tuxedo binary.

```sh
brew install tuxedo
```

--------------------------------

### Recurrence builder keybindings (keybinds.toml)

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Example of the [recurrence] table for the REPEAT overlay, which owns the keyboard while open. Its motions live in their own table and can reuse letters that mean something else in normal mode. Two-key chords are not supported here because the overlay has no leader state to arm.

```toml
[recurrence]
focus_next = ["j", "Down", "Tab"]        # move between interval / unit / mode
focus_prev = ["k", "Up", "Shift-Tab"]
value_next = ["l", "Right", "+", "="]    # change the focused field's value
value_prev = ["h", "Left", "-", "_"]
accept     = "Enter"                     # write the rec: token
cancel     = "Esc"

```

--------------------------------

### Standard todo.txt task with priority, date, context, project, and due extension

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Shows a standard todo.txt line with priority `(A)`, creation date `2026-04-28`, context `@phone`, project `+health`, and `due:` extension. Use this format for tasks with a due date.

```text
(A) 2026-04-28 Call dentist @phone +health due:2026-05-08
```

--------------------------------

### Run formatting, linting, and tests with mise

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Use these mise tasks to format, lint, and test the project. CI runs all three on every push and pull request. If you don't use mise, you can run the equivalent cargo commands directly.

```sh
mise run fmt      # cargo fmt --all
mise run clippy   # cargo clippy --all-targets --locked -- -D warnings
mise run test     # cargo test --locked
```

--------------------------------

### Clone and build tuxedo from source

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Clones the repository, builds a release binary, and runs it on a file. Requires the Rust 2024 edition.

```sh
git clone https://github.com/webstonehq/tuxedo
cd tuxedo
cargo build --release
./target/release/tuxedo [FILE]
```

--------------------------------

### Regenerate hero GIF with mise run demo

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Run this command to regenerate the hero GIF at the top of the README, recorded with vhs from docs/demo.tape.

```sh
mise run demo
```

--------------------------------

### Set notes_dir in config.toml

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Sets the base directory for resolving relative note:<path> tokens. If unset, tuxedo falls back to $NOTES_DIR and then ~/notes.

```toml
notes_dir = ~/notes
```

--------------------------------

### Set todo.txt environment variables

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Exports the TODO_DIR, TODO_FILE, and DONE_FILE variables used by tuxedo and todo.txt-cli.

```sh
export TODO_DIR="$HOME/Documents/todo"
export TODO_FILE="$TODO_DIR/todo.txt"
export DONE_FILE="$TODO_DIR/done.txt"
```

--------------------------------

### Completed task with completion date

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Shows a completed task prefixed with `x ` and a completion date. The format is `x <completion-date> <creation-date> <task>`. Use this when marking a task complete.

```text
x 2026-05-05 2026-05-01 Submit expense report +work
```

--------------------------------

### Regenerate screenshots with mise run screenshots

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Run this command to regenerate the checked-in SVG screenshots used in the README table.

```sh
mise run screenshots
```

--------------------------------

### JavaScript for capture, refresh, and rendering

Source: https://github.com/webstonehq/tuxedo/blob/main/src/serve/assets/index.html

This script runs in the browser for the capture page. It submits text to /add, refreshes tasks from /tasks, and renders open and inbox lists, parsing priority (A-Z) and date (YYYY-MM-DD) prefixes.

```JavaScript
(() => { const base = window.location.pathname.replace(/\/$/, ""); const $ = id => document.getElementById(id); function flash(msg, err) { const el = $("flash"); if (!msg) { el.innerHTML = ""; return; } el.innerHTML = '<div class="flash' + (err ? " err" : "") + '"></div>'; el.firstChild.textContent = msg; if (!err) setTimeout(() => { el.innerHTML = ""; }, 2500); } function render(list, items, emptyText) { list.innerHTML = ""; if (items.length === 0) { const li = document.createElement("li"); li.className = "empty"; li.textContent = emptyText; list.appendChild(li); return; } for (const raw of items) { const li = document.createElement("li"); const m = /^(?:\(([A-Z])\)\s+)?(?:(\d{4}-\d{2}-\d{2})\s+)?(.*)$/.exec(raw); if (m) { if (m[1]) { const s = document.createElement("span"); s.className = "prio"; s.textContent = "(" + m[1] + ") "; li.appendChild(s); } if (m[2]) { const s = document.createElement("span"); s.className = "meta"; s.textContent = m[2] + " "; li.appendChild(s); } li.appendChild(document.createTextNode(m[3])); } else { li.textContent = raw; } list.appendChild(li); } } async function refresh() { try { const r = await fetch(base + "/tasks", { cache: "no-store" }); if (!r.ok) throw new Error("status " + r.status); const body = await r.text(); const [openBlock, inboxBlock] = body.split("\n--- inbox (pending) ---\n", 2); const openLines = openBlock.split("\n").filter(l => l.length > 0 && !l.startsWith("x ")); const inboxLines = (inboxBlock || "").split("\n").filter(l => l.trim().length > 0); $("count-open").textContent = openLines.length; $("count-inbox").textContent = inboxLines.length; render($("open"), openLines, "no open tasks"); render($("inbox"), inboxLines, "—"); for (const li of $("inbox").children) li.classList.add("pending"); } catch (e) { flash("refresh failed: " + e.message, true); } } $("capture").addEventListener("submit", async (e) => { e.preventDefault(); const ta = $("text"); const text = ta.value.trim(); if (!text) return; try { const body = new URLSearchParams({ text }); const r = await fetch(base + "/add", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body, }); if (!r.ok) throw new Error("status " + r.status); ta.value = ""; flash("captured"); refresh(); } catch (err) { flash("add failed: " + err.message, true); } }); refresh(); setInterval(refresh, 3000); })();
```

--------------------------------

### Append tasks to inbox.txt via shell

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Use these shell commands to append tasks to the sibling inbox.txt file, which tuxedo picks up on its next external-change poll. Each line is processed through the same natural-language pipeline as the 'n' add prompt, given a creation date if missing, and merged into todo.txt as a single undoable batch. Plain shell appends do not take the advisory lock, so they are not serialized with the TUI drain.

```sh
echo "Refill prescription tomorrow" >> ~/notes/inbox.txt
```

```sh
echo "Call dentist due:2026-06-01" >> ~/notes/inbox.txt
```

--------------------------------

### Recurring task with due and rec extensions

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Shows a recurring task with `due:` and `rec:` extensions. Pressing `x` on this line marks it complete and inserts a new copy with the due date advanced by one month. The `u` key undoes both actions.

```text
2026-05-09 Pay rent due:2026-05-15 rec:+1m
```

--------------------------------

### Hide key:value tags with hide_keys

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Comma-separated list of keys whose tokens are hidden from task rows. Matching is case-insensitive; hiding is visual only and does not affect serialization or search.

```toml
hide_keys = uid, sync
```

--------------------------------

### Disable recurrence builder with recurrence_builder

Source: https://github.com/webstonehq/tuxedo/blob/main/README.md

Set recurrence_builder = false to skip the interactive REPEAT builder and type rec: values by hand. This is config-only and hot-reloads.

```toml
recurrence_builder = false
```
Tokens:
Raw