CLI & TUI Reference

Terminal Interface Reference

Strayfiles includes a terminal user interface (TUI) with vim-style keybindings. This reference covers all commands and shortcuts.

Launching the TUI

strayfiles

Or with a specific directory:

strayfiles ~/notes

Global Keybindings

These work in any mode:

Key	Action
q	Quit / Close dialog
?	Show help
Ctrl+c	Force quit
Esc	Cancel / Back

Navigation

File Browser

Key	Action
j / ↓	Move down
k / ↑	Move up
h / ←	Collapse / Go to parent
l / →	Expand / Enter directory
Enter	Open note
gg	Go to top
G	Go to bottom
Ctrl+d	Page down
Ctrl+u	Page up

Numbering Mode

Key	Action
1-9	Start number input
j / k	Move by count
Esc	Cancel numbering

Example: 5j moves down 5 items.

Editor Mode

The editor displays two modes:

• VIEW: Read-only markdown preview (for .md files)
• EDIT: Text editing with vim-style commands

Vim Commands (in EDIT mode)

Key	Action
i	Enter insert mode
a	Enter insert mode (after cursor)
o	New line below, enter insert
O	New line above, enter insert
I	Insert at line start
A	Insert at line end
s	Delete char and insert
S	Delete line and insert
dd	Delete line
yy	Yank (copy) line
cc	Change line
p	Paste below
u	Undo
Ctrl+r	Redo
~	Toggle case
x	Delete character

Movement Keys

Key	Action
h / j / k / l	Left / Down / Up / Right
w	Move to next word
e	Move to end of word
b	Move to previous word
0	Move to line start
$	Move to line end
^	Move to first non-blank
G	Move to end of file
gg	Move to top of file

Insert Mode

Key	Action
Esc	Return to normal mode
Regular typing	Insert text

Operators with Motions

Combine operators (d, y, c) with motions:

Command	Action
dw	Delete word
de	Delete to end of word
db	Delete to previous word
d$	Delete to end of line
d0	Delete to start of line
diw	Delete inside word
yw	Yank word
cw	Change word

Number Prefixes

Prefix any command with a number to repeat:

Command	Action
3j	Move down 3 lines
5dd	Delete 5 lines
2yy	Yank 2 lines
10G	Go to line 10

File Operations

Key	Action
:w	Save
:q	Quit
:wq	Save and quit
:e	Reload file

Discovery Mode

Key	Action
/	Open search
Enter	Execute search
Tab	Toggle file selection
Space	Toggle file selection
a	Select all
Enter (on results)	Add selected files

Dialog Navigation

Key	Action
Tab	Next field
Shift+Tab	Previous field
Enter	Confirm
Esc	Cancel
j / k	Navigate options

Search Syntax

Within the TUI search:

# Basic search
meeting notes

# Workspace filter
workspace:work

# Tag filter
tag:urgent

# Combined
workspace:work tag:api documentation

Status Bar

The status bar shows:

[mode] filename [modified] [sync status] [line:col]

• Mode: VIEW (preview) or EDIT (editing)
• Modified: [+] if unsaved changes
• Sync status: Connected, Disconnected, Syncing

Theme Customization

The TUI supports themes. Configure in settings:

~/.strayfiles/config.csv

Theme settings:

• Colors for syntax highlighting
• Status bar colors
• Selection colors

Markdown Preview

Key	Action
Ctrl+p	Toggle preview mode

Preview mode renders Markdown with syntax highlighting.

Command Mode

Enter command mode with ::

Command	Action
:w	Write (save)
:q	Quit
:wq	Write and quit
:q!	Quit without saving
:e	Reload
:set nu	Show line numbers
:set nonu	Hide line numbers
:help	Show help

Workspace Switching

Key	Action
gw	Open workspace picker
1-9	Quick switch to workspace

Tips

Quick navigation: Use gg and G to jump to start/end of file list.

Efficient editing: Use operators with motions (e.g., dw to delete word, de to delete to end of word).

Search workflow: / to search, n/N to navigate results, Esc to return to editing.

Multiple selections: In discovery mode, use Tab to select multiple files before adding.

Troubleshooting

Keys not working:

• Check terminal compatibility
• Some terminals intercept certain key combinations
• Try a different terminal emulator

Colors wrong:

• Ensure terminal supports 256 colors
• Set TERM=xterm-256color if needed

Unicode issues:

• Use a font with good Unicode support
• Check terminal encoding is UTF-8