🔁 Script playbooks for frequent commands in any terminal application
MIT License
Playbooks are interactive scripts that keep your recurring commands (or what you would otherwise search for in the bash history).
But playbooks are not just for bash, you can run them in any terminal application:
all without any further setup.
After installing the plugins, press <tmux-prefix> p
(default binding), this will split the current pane vertically and create or open a playbook in vim.
A playbook is a mixture of command history and script. It contains a list of commands that you can execute interactively in any order for any terminal application.
ls *.jpg
convert input.jpg output.png
convert input.jpg -resize 200x200 output.jpg
convert input.jpg -crop 200x200+50+50 output.jpg
convert input.jpg -rotate 90 output.jpg
You can send (execute) the commands to the target, which is a tmux pane following the playbook. Usually you use <Enter>
to execute one line. It's also possible to execute a selection or paragraph (<Leader>p
and <Leader>P
).
Treat your playbook like notes for a project. Unlike your shell history you can start a docker container, open a database client or even ssh to a remote system and then proceed to send commands to the executing application.
# connect remote
ssh myserver
# run psql
psql "host=localhost port=5432 dbname=postgres user=pg password=pg sslmode=disable"
psql "host=dbserver port=5432 dbname=postgres user=pg password=pg"
# run a query
select * from foo where bar='red';
# insert data etc.
insert into foo(bar, result) values('blue', 42);
While playbooks are organized by projects in folders, the target's location can be anywhere.
You can also make any document (like this README) into a temporary playbook by using the <Leader>p
key bindings or enabling <Enter>
with the :TomePlayBook
command.
Tome does not use variables because your shell already supports them.
# get an auth token, set base
export BASE=http://localhost:8080
export TOKEN=$(token-request)
# define a call function with defaults for httpie
call() { http -A bearer -a $TOKEN "$@"; }
id=$(call $BASE/car name==foostang | jq .[0].id)
call $BASE/car/$id
call PUT $BASE/car/$id color=blue
If you want a temporary scratch pad press <tmux-prefix> P
. It is also a good idea to paste commands here instead of directly into the terminal.
When you want multiple playbooks in a project just prefix them with .playbook-
, e.g. .playbook-db.sql
with the correct extension to get syntax highlighting.
Add laktak/tome to your favorite plugin manager.
E.g. for vim-plug place this in your .vimrc:
Plug 'laktak/tome'
then run the following in Vim:
:source %
:PlugInstall
To install Tome with the Tmux Plugin Manager simply add the plugin to the list of TPM plugins in .tmux.conf
:
set -g @plugin 'laktak/tome'
then and hit <tmux-prefix> I
to fetch the plugin and source it.
To install it manually, first clone the repo:
$ git clone https://github.com/laktak/tome ~/.tmux/tome
Add this line to the bottom of .tmux.conf
:
run-shell ~/.tmux/tome/tome.tmux
Reload the tmux environment:
# type this in terminal
$ tmux source-file ~/.tmux.conf
By default Tome has the following mappings:
nmap <Leader>p <Plug>(TomePlayLine)
nmap <Leader>P <Plug>(TomePlayParagraph)
xmap <Leader>p <Plug>(TomePlaySelection)
If you prefer to create them yourself set
let g:tome_no_mappings = 1
Tome has a no send list to avoid accidentially sending input to a tui application. By default this includes lf
(the file manager) and vim
. Set your own list with
let g:tome_no_send = ['vim', 'lf', 'gitui']
If you do not want to automatically open .playbook*
files as playbooks you can set
let g:tome_no_auto = 1
You can set any of these options by adding them to your ~/.tmux.conf
file:
set -g <option> "<value>"
Where <option>
and <value>
correspond to one of the options specified below
Option | Default | Description |
---|---|---|
@tome_key |
p |
The key binding to open a Tome playbook. |
@tome_scratch_key |
P |
The key binding to open a Tome scratchpad. |
@tome_height |
8 |
Height of the playbook vertial split. |
@tome_playbook |
.playbook.sh |
Name of the playbook to open. |