toe

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Getting Started#

toe is a modal terminal editor built for Go development. toe edits Go projects, not the universe.

Requirements#

Go 1.26 or later
A terminal with ANSI color support

Installing#

git clone https://github.com/kode4food/toe
cd toe
make install # installs to $GOPATH/bin

Or build without installing:

make build # writes to dist/toe

Opening Files#

toe # open in current directory
toe path/to/file.go # open a single file
toe file1.go file2.go # open multiple files

Modes#

toe is a modal editor. Every key press means something different depending on the current mode.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration#

Config Files#

toe reads config in this order (later values override earlier ones):

File	Purpose
`$XDG_CONFIG_HOME/toe/config.toml`	User config
`$XDG_CONFIG_HOME/toe/languages.toml`	User language config
`.toe/config.toml`	Workspace config (trusted workspaces only)
`.toe/languages.toml`	Workspace language config (trusted workspaces only)

$XDG_CONFIG_HOME defaults to ~/.config.

Open your user config directly: :config_open
Open workspace config: :config_open_workspace
Reload after editing: :config_reload

Workspace Trust#

Workspace-local config files (.toe/config.toml and .toe/languages.toml) are only loaded for trusted workspaces. Untrusted workspaces silently skip these files — only user config applies.

Key Bindings

Mon, 01 Jan 0001 00:00:00 +0000

Key Bindings#

Normal Mode#

Motion#

Key	Action
`h` / `←`	Move left
`j` / `↓`	Move down
`k` / `↑`	Move up
`l` / `→`	Move right
`w`	Move to start of next word
`b`	Move to start of previous word
`e`	Move to end of next word
`W`	Move to start of next long word
`B`	Move to start of previous long word
`E`	Move to end of next long word
`f<char>`	Move to next occurrence of char
`t<char>`	Move till next occurrence of char
`F<char>`	Move to previous occurrence of char
`T<char>`	Move till previous occurrence of char
`Home`	Goto line start
`End`	Goto line end
`gg` / `<n>gg`	Goto line number `<n>` else file start
`G` / `<n>G`	Goto line
`gs`	Goto first non-blank in line
`ge`	Goto last line
`g\|` / `<n>g\|`	Goto column
`]p`	Goto next paragraph
`[p`	Goto previous paragraph

Goto Prefix (`g`)#

Key	Action
`gd`	Goto definition
`gD`	Goto declaration
`gy`	Goto type definition
`gi`	Goto implementation
`gr`	Goto references
`gf`	Goto files/URLs in selections
`gn`	Goto next buffer
`gp`	Goto previous buffer
`ga`	Goto last accessed file
`gm`	Goto last modified file
`g.`	Goto last modification
`gt`	Goto window top
`gc`	Goto window center
`gb`	Goto window bottom

Jumplist#

Key	Action
`Ctrl+o`	Jump backward on jumplist
`Ctrl+i` / `Tab`	Jump forward on jumplist
`Ctrl+s`	Save current selection to jumplist

Entering Other Modes#

Key	Action
`:`	Enter command mode
`i`	Insert before selection
`I`	Insert at start of line
`a`	Append after selection
`A`	Insert at end of line
`o`	Open new line below selection
`O`	Open new line above selection
`v`	Enter selection extend mode

Editing#

Key	Action
`d`	Delete selection
`Alt+d`	Delete selection without yanking
`c`	Change selection
`Alt+c`	Change selection without yanking
`r<char>`	Replace with new char
`u`	Undo change
`U`	Redo change
`Alt+u`	Move backward in history
`Alt+U`	Move forward in history
`~`	Switch (toggle) case
`	Switch to lowercase
Alt+`` ``	Switch to uppercase
`>`	Indent selection
`<`	Unindent selection
`J`	Join lines inside selection
`Alt+J`	Join lines inside selection and select spaces
`&`	Align selections in column
`_`	Trim whitespace from selections
`Ctrl+a`	Increment item under cursor
`Ctrl+x`	Decrement item under cursor
`=`	Format selection

Yank and Paste#

Key	Action
`y`	Yank selection
`p`	Paste after selection
`P`	Paste before selection
`R`	Replace with yanked text
`Space+y`	Yank selections to clipboard
`Space+Y`	Yank main selection to clipboard
`Space+p`	Paste clipboard after selections
`Space+P`	Paste clipboard before selections
`Space+R`	Replace selections by clipboard content
`"<reg>`	Select register

Search#

Key	Action
`/`	Search for regex pattern
`?`	Reverse search for regex pattern
`n`	Select next search match
`N`	Select previous search match
`*`	Use current selection as search pattern, word bounded
`Alt+*`	Use current selection as search pattern

Selection Manipulation#

Key	Action
`s`	Select all regex matches inside selections
`S`	Split selections on regex matches
`K`	Keep selections matching regex
`Alt+K`	Remove selections matching regex
`Alt+s`	Split selection on newlines
`;`	Collapse selection into single cursor
`Alt+;`	Flip selection cursor and anchor
`%`	Select whole document
`x`	Select current line, if already selected, extend to next line
`X`	Extend selection to line bounds
`Alt+x`	Shrink selection to line bounds
`,`	Keep primary selection
`Alt+,`	Remove primary selection
`(`	Rotate selections backward
`)`	Rotate selections forward
`Alt+(`	Rotate selections contents backward
`Alt+)`	Rotate selection contents forward
`Alt+:`	Ensure all selections face forward
`C`	Copy selection on next line
`Alt+C`	Copy selection on previous line
`Alt+-`	Merge selections
`Alt+_`	Merge consecutive selections
`Alt+.`	Repeat last motion

Match (`m` prefix)#

Key	Action
`mm`	Goto matching bracket
`ms<char>`	Surround add
`mr<from><to>`	Surround replace
`md<char>`	Surround delete
`ma<char>`	Select around object
`mi<char>`	Select inside object

View / Scroll (`z` / `Z` prefix)#

Key	Action
`zz` / `zc` / `Zz` / `Zc`	Align view center
`zt` / `z.` / `Zt` / `Z.`	Align view top
`zb` / `Zb`	Align view bottom
`zk` / `z↑` / `Zk` / `Z↑`	Scroll view up
`zj` / `z↓` / `Zj` / `Z↓`	Scroll view down
`Ctrl+b` / `PageUp`	Move page up
`Ctrl+f` / `PageDown`	Move page down
`Ctrl+u`	Move page and cursor half up
`Ctrl+d`	Move page and cursor half down

Splits (`Ctrl+w` or `Space+w`)#

Key	Action
`Ctrl+w v` / `Ctrl+w Ctrl+v`	Vertical right split
`Ctrl+w s` / `Ctrl+w Ctrl+s`	Horizontal bottom split
`Ctrl+w n v` / `Ctrl+w n Ctrl+v`	Vertical right split scratch buffer
`Ctrl+w n s` / `Ctrl+w n Ctrl+s`	Horizontal bottom split scratch buffer
`Ctrl+w q` / `Ctrl+w Ctrl+q`	Close window
`Ctrl+w o` / `Ctrl+w Ctrl+o`	Close windows except current
`Ctrl+w w` / `Ctrl+w Ctrl+w`	Goto next window
`Ctrl+w t` / `Ctrl+w Ctrl+t`	Transpose splits
`Ctrl+w h/j/k/l` / `Ctrl+w Ctrl+h/j/k/l`	Jump to left/below/above/right split
`Ctrl+w H/J/K/L`	Swap with left/below/above/right split

All Ctrl+w bindings also work with Space+w.

Commands

Mon, 01 Jan 0001 00:00:00 +0000

Commands#

Enter command mode with :. All commands can be used by their full name or any listed alias.

File#

Command	Aliases	Description
`write`	`w`	Write changes to disk. Accepts an optional path
`write!`	`w!`	Force write, creating necessary subdirectories. Accepts an optional path
`write_all`	`write-all`, `wa`	Write changes from all buffers to disk
`write-all!`	`wa!`	Forcefully write all buffers, creating necessary subdirectories
`write_quit`	`write-quit`, `wq`, `exit`, `x`, `xit`	Write changes and close the current view. Accepts an optional path
`write-quit!`	`wq!`, `exit!`, `x!`, `xit!`	Write and close the current view forcefully. Accepts an optional path
`write_quit_all`	`write-quit-all`, `wqa`, `xa`	Write all buffers and close all views
`write-quit-all!`	`wqa!`, `xa!`	Forcefully write all buffers, creating necessary subdirectories, and close all views
`write_buffer_close`	`write-buffer-close`, `wbc`	Write changes and close the buffer. Accepts an optional path
`write-buffer-close!`	`wbc!`	Force write and close the buffer, creating necessary subdirectories. Accepts an optional path
`update`	`u`	Write changes only if the file has been modified
`open`	`o`, `edit`, `e`	Open a file from disk into the current view
`new`	`n`	Create a new scratch buffer
`reload`	`rl`	Discard changes and reload from the source file
`reload_all`	`reload-all`, `rla`	Discard changes and reload all documents from the source files
`move`	`mv`	Move the current buffer and its corresponding file to a different path
`move!`	`mv!`	Move the current buffer and file, creating necessary subdirectories
`read`	`r`	Load a file into buffer at the cursor

Buffer#

Command	Aliases	Description
`buffer_close`	`buffer-close`, `bc`, `bclose`	Close the current buffer
`buffer_close_force`	`buffer-close!`, `bc!`, `bclose!`	Close the current buffer forcefully, ignoring unsaved changes
`buffer_close_others`	`buffer-close-others`, `bco`, `bcloseother`	Close all buffers but the currently focused one
`buffer_close_all`	`buffer-close-all`, `bca`, `bcloseall`	Close all buffers without quitting
`buffer_next`	`buffer-next`, `bn`, `bnext`	Goto next buffer
`buffer_previous`	`buffer-previous`, `bp`, `bprev`	Goto previous buffer

Window#

Command	Aliases	Description
`vsplit`	`vs`	Vertical right split
`split`	`hs`, `sp`	Horizontal bottom split
`vsplit_new`	`vnew`	Vertical right split scratch buffer
`hsplit_new`	`hnew`	Horizontal bottom split scratch buffer
`transpose_view`		Transpose splits
`wclose`	`wc`	Close window
`wclose!`	`wc!`	Force close window
`wonly`	`wo`	Close windows except current

Quit#

Command	Aliases	Description
`quit`	`q`	Close the current view
`quit!`	`q!`	Force close the current view, ignoring unsaved changes
`quit_all`	`quit-all`, `qa`	Close all views
`quit-all!`	`qa!`	Force close all views ignoring unsaved changes
`cquit`	`cq`	Quit with exit code (default 1)
`cquit!`	`cq!`	Force quit with exit code (default 1) ignoring unsaved changes

Command	Aliases	Description
`goto`	`g`	Goto line number

Directory#

Command	Aliases	Description
`change_directory`	`change-current-directory`, `cd`	Change the current working directory
`show_directory`	`show-directory`, `pwd`	Show the current working directory
`show_directory_stack`	`show-directory-stack`	Show the directory stack as a space delimited string
`push_directory`	`push-directory`, `pushd`	Save and then change the current directory
`pop_directory`	`pop-directory`, `popd`	Remove the top entry from the directory stack and cd to the new top directory

Config#

Command	Aliases	Description
`get_option`	`get-option`, `get`	Get the current value of a config option
`set_option`	`set-option`, `set`	Set a config option at runtime
`toggle_option`	`toggle-option`, `toggle`	Toggle a config option at runtime
`config_open`	`config-open`	Open the user config.toml file
`config_open_workspace`	`config-open-workspace`	Open the workspace config.toml file
`config_reload`	`config-reload`	Refresh user config
`theme`		Change the editor theme (show current theme if no name specified)
`log_open`	`log-open`	Open the editor log file

Workspace Trust#

Command	Aliases	Description
`workspace_trust`	`workspace-trust`	Add current workspace to the list of trusted workspaces
`workspace_untrust`	`workspace-untrust`	Remove current workspace from the list of trusted workspaces

Session#

Command	Aliases	Description
`save_session`	`save-session`	Save session to the workspace session file
`restore_session`	`restore-session`	Restore session from the workspace session file

Format#

Command	Aliases	Description
`format`	`fmt`	Format the file using an external formatter or language server
`reflow`		Hard-wrap the current selection of lines to a given width. Accepts an optional width argument (defaults to `editor.text-width`)
`sort`		Sort ranges in selection. Flags: `-r`/`--reverse`, `-i`/`--insensitive`

LSP#

Command	Aliases	Description
`goto_declaration`		Goto declaration
`goto_definition`		Goto definition
`goto_type_definition`		Goto type definition
`goto_implementation`		Goto implementation
`goto_reference`		Goto references
`select_references_to_symbol_under_cursor`		Select symbol references
`code_action`		Perform code action
`hover`		Show docs for item under cursor
`rename_symbol`		Rename symbol
`signature-help`		Show signature help
`symbol_picker`		Open symbol picker
`workspace_symbol_picker`		Open workspace symbol picker
`lsp-restart`		Restart language servers for the current document
`lsp-stop`		Stop language servers for the current document
`lsp-workspace-command`		Execute a language server workspace command

Clipboard#

Command	Aliases	Description
`yank`	`clipboard-yank`	Yank selection
`paste_after`		Paste after selection
`paste_before`		Paste before selection
`replace_with_yanked`		Replace with yanked text
`yank_to_clipboard`		Yank selections to clipboard
`yank_main_selection_to_clipboard`		Yank main selection to clipboard
`paste_clipboard_after`	`clipboard-paste-after`	Paste clipboard after selections
`paste_clipboard_before`	`clipboard-paste-before`	Paste clipboard before selections
`clipboard_paste_replace`	`clipboard-paste-replace`	Replace selections by clipboard content
`yank_joined_to_clipboard`	`yank-join`	Yank joined selections. Accepts an optional separator argument
`yank_to_primary_clipboard`	`primary-clipboard-yank`	Yank selections to primary clipboard
`paste_primary_clipboard_after`	`primary-clipboard-paste-after`	Paste primary clipboard after selections
`paste_primary_clipboard_before`	`primary-clipboard-paste-before`	Paste primary clipboard before selections
`primary_clipboard_paste_replace`	`primary-clipboard-paste-replace`	Replace selections by primary clipboard
`clear_register`	`clear-register`	Clear given register. If no argument is given, clear all registers
`show_clipboard_provider`	`show-clipboard-provider`	Show clipboard provider name in status bar

Search#

Command	Aliases	Description
`search_forward`		Search for regex pattern (forward)
`search_backward`		Reverse search for regex pattern
`search_next`		Select next search match
`search_prev`		Select previous search match
`search_selection_word`		Use current selection as search pattern, word bounded
`make_search_word_bounded`		Modify current search to make it word bounded
`search_selection`		Use current selection as search pattern

Support#

Command	Aliases	Description
`character_info`	`character-info`, `char`	Get info about the character under the primary cursor
`echo`		Prints the given arguments to the statusline
`redraw`		Clear and re-render the whole UI

Sessions

Mon, 01 Jan 0001 00:00:00 +0000

Sessions#

toe can save and restore your editing session: the set of open documents, split layout, cursor positions, view modes, and editor options.

Session File#

Sessions are stored in .toe/session.toml at your project root (the workspace directory). Each project has its own independent session.

Auto-Session#

When editor.auto-session is enabled (the default), toe automatically:

Restores the previous session when launched with no file arguments
Saves the current session when you quit

# ~/.config/toe/config.toml
[editor]
auto-session = true # default: true

To disable auto-session:

Language Servers

Mon, 01 Jan 0001 00:00:00 +0000

Language Servers#

toe is a Go editor. LSP support is built around gopls for Go, with additional servers available for web languages (TypeScript, HTML, CSS) and other tools in the Go ecosystem. Each language specifies which server to use; you configure servers in your languages.toml.

Configuring a Language Server#

Add a [language-server.<name>] section and reference it from the language:

# $XDG_CONFIG_HOME/toe/languages.toml

[language-server.gopls]
command = "gopls"
args = ["-remote=auto"] # optional
environment = { GOFLAGS = "-mod=mod" } # optional
timeout = 30 # optional, seconds

[[language]]
name = "go"
language-servers = ["gopls"]

Workspace Config#

Language server config in .toe/languages.toml is merged on top of user config, letting you override per-project without touching global settings.

toe

Getting Started

Getting Started#

Requirements#

Installing#

Opening Files#

Modes#

Configuration

Configuration#

Config Files#

Workspace Trust#

Key Bindings

Key Bindings#

Normal Mode#

Motion#

Goto Prefix (g)#

Jumplist#

Entering Other Modes#

Editing#

Yank and Paste#

Search#

Selection Manipulation#

Match (m prefix)#

View / Scroll (z / Z prefix)#

Splits (Ctrl+w or Space+w)#

Commands

Commands#

File#

Buffer#

Window#

Quit#

Navigation#

Directory#

Config#

Workspace Trust#

Session#

Format#

LSP#

Clipboard#

Search#

Support#

Sessions

Sessions#

Session File#

Auto-Session#

Language Servers

Language Servers#

Configuring a Language Server#

Workspace Config#

Goto Prefix (`g`)#

Match (`m` prefix)#

View / Scroll (`z` / `Z` prefix)#

Splits (`Ctrl+w` or `Space+w`)#