The Textsmith manual on The Textsmith

Installing

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

The Textsmith runs on Linux, under X11 and Wayland. It needs GTK 3 and VTE (2.91), which most desktops already have.

With one command

curl -fsSL https://thetextsmith.com/install.sh | sh

On Debian, Ubuntu and Linux Mint, this adds The Textsmith’s apt repository and installs the textsmith package; on Arch, the pacman repository. On other distributions it puts The Textsmith in ~/.local/bin. The repositories are signed with The Textsmith release key, fingerprint EACA 85A8 8536 7887 6820 15F8 9364 9288 FCB4 8B9E, and new versions then arrive with your usual system updates.

First steps

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

Start The Textsmith from your application menu or with your shortcut. You get your usual shell, bash or zsh, with your own ~/.bashrc or ~/.zshrc read first. The Textsmith then adds its own small hooks, which make bookmarks and the review buffer work. Other shells start bash.

Everything you know still works: Ctrl+R searches history, Tab completes, Ctrl+C stops a program. The Textsmith adds a handful of keys of its own (see Keys), and only at the shell’s prompt: while a program runs, every key goes to it unchanged.

Bookmarks

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

A bookmark is a command you save once and run by name. The Textsmith keeps them in one plain text file, bookmarks, one per line, which you can edit by hand and carry between machines.

Making a bookmark

Type the command as a comment, with a name and a colon in front, then press Alt+M:

#vps: ssh forge

The line is saved as a bookmark called vps. Alt+M on a line without a label bookmarks it as it is; on an empty line, it bookmarks the last command you ran. Pressing Alt+M on a bookmark that is already there removes it. Alt+Shift+M saves the bookmark and runs it at once.

A command per machine

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

When your bookmarks travel between machines, in your dotfiles for instance, one name can stand for a different command on each:

#update: [:anvil "sudo apt update && sudo apt upgrade -y", :brainpower "sudo pacman -Syu", :hammer "sudo dnf update"]

update then runs the command for the machine it is on. Several machines can share a command (:anvil :forge "..."), and :* stands for any other machine. Each command can have places, defaults and <..> of its own. Commands go in double quotes (with \" for a quote inside) or in single quotes. On a machine with no command and no :*, the bookmark says so and runs nothing.

Inside ssh, tmux and other programs

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

Bookmarks run at your own shell’s prompt. Inside ssh, tmux or any other program, the shell is not The Textsmith’s, so #@, Alt+Enter and Alt+M do not apply there. The bookmark list does: while a program runs, choosing a bookmark types its command into the program without pressing Enter, so you can hear it and then press Enter yourself. A bookmark that takes arguments is typed with its places (<file>) for you to replace.

Bookmarks in other terminals

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

Bookmarks need not stay in The Textsmith. textsmith bm export writes them as ordinary bash and zsh functions:

textsmith bm export -o ~/.config/textsmith/bookmarks.sh

Then, in ~/.bashrc or ~/.zshrc on any machine or terminal:

[ -f ~/.config/textsmith/bookmarks.sh ] && . ~/.config/textsmith/bookmarks.sh

Each bookmark becomes a function of the same name. It takes the same arguments and says the same sentence when they are wrong:

site() {
 (( $# == 2 )) || { printf '%s\n' 'site takes 2 arguments: source, destination; you gave '"$#." >&2; return 2; }
 rsync -rltvP --delete "${1}" forge:/var/www/"${2}"
}

Defaults, <..>, counts and commands per machine all carry over. A piped bookmark becomes a function to pipe into: ls | count. Bookmarks without a name, and additions that are not commands on their own (#quiet: 2>/dev/null), are left out. Run the export again after changing your bookmarks.

The review buffer

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

F4 opens a read-only view of the tab’s session: each command on a line of its own, $ make (failed, exit 2), and its output under it. The cursor starts on the last command.

The arrow keys and the usual text keys read it. Shift with them selects, and Ctrl+C copies.
Alt+Up and Alt+Down: the previous and next command.
Alt+PageUp and Alt+PageDown: the previous and next command that failed.
Alt+End: the last command, with the newest output.
Escape or F4: back to the terminal.

The output is taken when each command finishes, so progress bars show as they ended. Full-screen programs such as vim are not in the review, only what they left on the normal screen.

Keys

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

Key	What it does
F1	This manual, in your web browser
Ctrl+F1	About The Textsmith
F4	The review buffer, and back
Alt+Enter	Run the line as a bookmark call
Alt+Shift+Enter	Fill the bookmark call in without running it
Shift+Enter	Run the line with sudo
Alt+M	Bookmark the line (or the last command), or remove that bookmark
Alt+Shift+M	Bookmark the line and run it
Alt+Shift+B	The bookmark list
Tab, Shift+Tab	Complete: the next and previous choice
Ctrl+Shift+C, Ctrl+Shift+V	Copy, paste
Ctrl+Shift+T, Ctrl+Shift+W	New tab, close tab
Ctrl+PageDown, Ctrl+PageUp	Next tab, previous tab
Ctrl+Comma	Open the preferences file

In the review buffer: Alt+Up, Alt+Down, Alt+PageUp, Alt+PageDown and Alt+End, as above.

Preferences

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

The Textsmith keeps your bookmarks and preferences in one folder, the first of these that applies:

TEXTSMITH_CONFIG (or TEXTSMITH_HOME), if you set it;
~/.textsmith, if it is there (earlier versions used it);
~/.config/textsmith, or $XDG_CONFIG_HOME/textsmith.

textsmith --config-dir says which one is in use.

The preferences are in gtk-prefs.json, written with every default the first time The Textsmith starts. Ctrl+Comma opens it in your text editor, and it is read again when the window gets the focus back.

With a screen reader

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

The Textsmith is tested with Orca on GNOME and MATE. Some notes:

Typing, the cursor and new output are read by Orca as in GNOME Terminal. Enter and Tab do not make it read your prompt again.
For long output, F4 is the review buffer: a text view, where Orca’s usual reading keys work, with jumps between commands.
Alt+Shift with the arrows are Orca’s table keys, so The Textsmith leaves them alone; failed commands are on Alt+PageUp and Alt+PageDown.
When a key has nothing to report (“No earlier command”, a bookmark mistake), The Textsmith says so through the accessibility layer, once.

Help and feedback

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

The site, with this manual and news: https://thetextsmith.com
Under the Anvil, the blog about working with text and the shell: https://thetextsmith.com/blog/
Questions, bugs and ideas: the issue tracker, https://github.com/thetextsmith/textsmith/issues.

Copyright 2026 Ishe Chinyoka. The Textsmith is free software: you can redistribute it and change it under the terms of the GNU General Public License, version 3 or (at your option) any later version. It comes with no warranty. The full licence is in the LICENSE file and in the About window.