{"id":13739809,"url":"https://github.com/laktak/tome","last_synced_at":"2025-04-09T09:05:29.483Z","repository":{"id":238194893,"uuid":"796066605","full_name":"laktak/tome","owner":"laktak","description":"🔁 Interactive Script playbooks for your terminal with Vim/Neovim (and Tmux)","archived":false,"fork":false,"pushed_at":"2025-02-27T08:57:20.000Z","size":45,"stargazers_count":94,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-02T08:06:03.931Z","etag":null,"topics":["automation","history","neovim-plugin","shell","shell-history","tmux","tmux-plugin","vim","vim-plugin"],"latest_commit_sha":null,"homepage":"","language":"Vim Script","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/laktak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-04T20:47:33.000Z","updated_at":"2025-04-02T07:42:16.000Z","dependencies_parsed_at":"2024-05-09T16:30:48.644Z","dependency_job_id":"f566beec-17ea-4275-baad-81f06d4cd0ed","html_url":"https://github.com/laktak/tome","commit_stats":{"total_commits":10,"total_committers":1,"mean_commits":10.0,"dds":0.0,"last_synced_commit":"a9afdbe6490ecd5d2d66bc024b7d53a3b616f137"},"previous_names":["laktak/tome"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laktak%2Ftome","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laktak%2Ftome/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laktak%2Ftome/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laktak%2Ftome/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/laktak","download_url":"https://codeload.github.com/laktak/tome/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248008630,"owners_count":21032556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","history","neovim-plugin","shell","shell-history","tmux","tmux-plugin","vim","vim-plugin"],"created_at":"2024-08-03T04:00:37.852Z","updated_at":"2025-04-09T09:05:29.464Z","avatar_url":"https://github.com/laktak.png","language":"Vim Script","funding_links":[],"categories":["Vim Script","Terminal Integration","\u003ca name=\"cheatsheet\"\u003e\u003c/a\u003eCommands cheatsheet and snippets","\u003ca name=\"tools\"\u003e\u003c/a\u003eTools and session management"],"sub_categories":["CSV Files"],"readme":"\n# 🔁 TOME Playbooks\n\nPlaybooks are a simple but powerful tool for your shell and terminal apps.\n\nTome puts Vim \"above\", where you write and collect your commands which are then executed, on demand, in the terminal below. Instead of a one line prompt you can edit with Vim and instead of a history you can see all your commands in the document.\n\n1. Replaces your command history, organized by project\n2. Allows interactive scripting\n3. Allows you to add notes - we may even call it documentation ;)\n4. Enhances your shell prompt with Vim\n5. Built for tmux or the Vim terminal\n\n![intro](https://github.com/laktak/tome/wiki/assets/intro1.gif)\n\n\n- [Introduction](#introduction)\n- [Requirements](#requirements)\n- [Installation](#installation)\n  - [Vim plugin](#vim-plugin)\n  - [tmux plugin (optional)](#tmux-plugin-optional)\n- [Scripting](#scripting)\n- [Configuration](#configuration)\n  - [Vim options](#vim-options)\n  - [tmux options](#tmux-options)\n\n\n## Introduction\n\n- With tmux: press `\u003ctmux-prefix\u003e p` (default binding), this will split the current pane vertically and create or open a playbook in Vim\n- With Vim only: run `vim .playbook.sh` or open a playbook file\n\nA playbook is a mixture of command history, script and documentation. You can structure it however you like. On any line that you want to send to the terminal just press enter. This can be any shell but also a terminal application like a SQL client or ssh to a remote server.\n\n```\nls *.jpg\nconvert input.jpg output.png\nconvert input.jpg -resize 200x200 output.jpg\nconvert input.jpg -crop 200x200+50+50 output.jpg\nconvert input.jpg -rotate 90 output.jpg\n```\n\nYou can send (execute) the commands to the target, which is a tmux pane following the playbook. Usually you use `\u003cEnter\u003e` to execute one line. It's also possible to execute a selection or paragraph (`\u003cLeader\u003ep` and `\u003cLeader\u003eP`).\n\nTreat 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.\n\n```\n# connect remote\nssh myserver\n\n# run psql\npsql \"host=localhost port=5432 dbname=postgres user=pg password=pg sslmode=disable\"\npsql \"host=dbserver port=5432 dbname=postgres user=pg password=pg\"\n\n# run a query\nselect * from foo where bar='red';\n\n# insert data etc.\ninsert into foo(bar, result) values('blue', 42);\n```\n\n\nWhile playbooks are organized by projects in folders, the target's location can be anywhere (meaning you can include a `cd` to another location in your playbook).\n\nYou can also make any document (like this README) into a temporary playbook by using the `\u003cLeader\u003ep` key bindings or enabling `\u003cEnter\u003e` with the `:TomePlayBook` command.\n\nNote: the $ indicator at the beginning of a line for shell commands (like in some READMEs) will be ignored so you can run the command directly.\n\n\nYour shell already has variables so typically you would not need them in Tome.\n\n```\n# this Bash example defines BASE with a constant\nexport BASE=http://localhost:8080\n# and TOKEN using a shell script\nexport TOKEN=$(token-request)\n# \"call\" can be another script or defined directly in Tome:\ncall() { http -A bearer -a $TOKEN \"$@\"; }\n\n# use everything together\nid=$(call $BASE/car name==foostang | jq .[0].id)\ncall $BASE/car/$id\n  call PUT $BASE/car/$id color=blue\n```\n\nIf you prefer, or if the target has no variables, you can use Tome variables (string replacement only).\n\n- Variables are enclosed in `$\u003c` and `\u003e`, like `$\u003cfoo\u003e`.\n- Variables are defined with `$\u003cNAME\u003e=VALUE`, like `$\u003cfoo\u003e=some text`.\n- Any variable is replaced with its defined value, no other operations are performed.\n- If a variable is undefined Tome will open a scratchpad with the missing variables. Don't forget to send the values with `\u003cEnter\u003e`!\n- To escape the text `$\u003ctext\u003e` use `$\u003c\u003ctext\u003e`\n\n```\n# set a BASE variable\n$\u003cbase\u003e=http://localhost:8080\n# use in a command\necho $\u003cbase\u003e\n# undefined variables open a scratchpad\necho $\u003cfoo\u003e\n# escaped, not a variable\necho \"$\u003c\u003cfoo\u003e\"\n```\n\nOn tmux: if you want a temporary scratch pad press `\u003ctmux-prefix\u003e P`. It is also a good idea to paste commands here instead of directly into the terminal.\n\nWhen 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.\n\n\n## Requirements\n\n- Vim or Neovim\n- any REPL, e.g. bash, a database client, etc.\n- tmux optional (but recommended)\n\n\n## Installation\n\n### Vim plugin\n\nAdd laktak/tome to your favorite plugin manager.\n\nE.g. for [vim-plug](https://github.com/junegunn/vim-plug/) place this in your `.vimrc`:\n\n```\nPlug 'laktak/tome'\n```\n\nthen run the following in Vim:\n\n```\n:source %\n:PlugInstall\n```\n\n\n### tmux plugin (optional)\n\nTo install Tome with the [Tmux Plugin Manager](https://github.com/tmux-plugins/tpm) simply add the plugin to the list of TPM plugins in `.tmux.conf`:\n\n```\nset -g @plugin 'laktak/tome'\n```\n\nthen and hit `\u003ctmux-prefix\u003e I` to fetch the plugin and source it.\n\n\nTo install it manually, first clone the repo:\n\n```\n$ git clone https://github.com/laktak/tome ~/.tmux/tome\n```\n\nAdd this line to the bottom of `.tmux.conf`:\n\n```\nrun-shell ~/.tmux/tome/tome.tmux\n```\n\nReload the tmux environment:\n\n```\n# type this in terminal\n$ tmux source-file ~/.tmux.conf\n```\n\n\n## Scripting\n\nIf you want to open a playbook from a script you can use the `tome-open-playbook` command. It can be found where you installed the tmux plugin.\n\n```\nUsage: tome-open-playbook [-s] [-l height]\n```\n\n- `-s` will open a scratchpad\n- `-l` allows you to specify a height\n\n\n## Configuration\n\n\n### Vim options\n\nBy default Tome has the following mappings:\n\n```\nnmap \u003cLeader\u003ep \u003cPlug\u003e(TomePlayLine)\nnmap \u003cLeader\u003eP \u003cPlug\u003e(TomePlayParagraph)\nxmap \u003cLeader\u003ep \u003cPlug\u003e(TomePlaySelection)\n```\n\n[See `help TomeConfig`](doc/tome.txt) in Vim to change them, and for more options.\n\n\n### tmux options\n\nYou can set any of these options by adding them to your `~/.tmux.conf` file:\n\n```\nset -g \u003coption\u003e \"\u003cvalue\u003e\"\n```\n\nWhere `\u003coption\u003e` and `\u003cvalue\u003e` correspond to one of the options specified below\n\n| Option                 | Default         | Description |\n| :---                   | :---:           | :--- |\n| `@tome_key`            | `p`             | The key binding to open a Tome playbook. |\n| `@tome_scratch_key`    | `P`             | The key binding to open a Tome scratchpad. |\n| `@tome_height`         | `8`             | Height of the playbook vertial split. |\n| `@tome_editor`         | detect (n)vim   | Manually set your preferred editor. |\n| `@tome_playbook`       | `.playbook.sh`  | Name of the playbook to open. |\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaktak%2Ftome","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaktak%2Ftome","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaktak%2Ftome/lists"}