An utility for sending keyboard macros to Spacemacs or DOOM Emacs via emacsclient.
SPC was born as an integration utility to make other applications interact with DOOM/Spacemacs by sending keystrokes.
For example, you can instruct iTerm2 to open a file on click by giving it the following Spacemacs macro using evil commands:
SPC ff -r "$FILE" "$LINE" gg "$COL" lUsing SPC you can make your life on the terminal a bit more comfortable and automate
some things that can invoke Emacs macros. eg. creating ORG Agenda entries or using Magit.
SPC is not limited to be used by DOOM/Spacemacs, it is handy as well on any Emacs
configuration and will happily send any keyboard macro from the terminal into Emacs
just as if you would have typed it.
Just download bin/SPC and place it somewhere in your PATH.
It will need basic coreutils and base64 command for sending raw inputs.
This repo is Nix enabled and can be run using:
nix run github:vic/SPC -- --help
Some people might also want to create several command aliases to ease frequent use cases. See the [Integrations] section.
SPC expects an Emacs daemon to be already running and ready to receive keyboard macros.
You can start such a daemon manually within Emacs by executing M-x server-start.
There are many options that let you customize how SPC talks to your Emacs daemon.
Running SPC --help shows the command usage, included here for reference:
SPC - Send a SPC keyboard macro to Spacemacs or DOOM Emacs via emacsclient.
USAGE
SPC [OPTION..] [KEYS..] [-- emacsclient options]
KEYS are key sequence strings in the format accepted by `(kbd)` and as
returned by commands such as `C-h k` in Emacs.
OPTIONS
-D, --describe
Causes emacs to print a brief description of the received
key sequence. This option is useful when debugging or
constructing your first keyboard macro.
-r, --raw <INPUT>
Sends INPUT as if it was directly typed on Emacs.
Since raw inputs can be any byte sequence they are encoded
using the `base64` command and decoded on the Emacs daemon.
This is useful for sending keys that otherwise would be
interpreted as options for SPC itself.
eg. `-r --lisp` will send `(kbd "- - l i s p")` to Emacs.
-f, --file-raw <FILE>
Sends all content from FILE as if directly typed on Emacs.
-f-, --stdin
Sends all content from STDIN as if directly typed on Emacs.
-l, --lisp <CODE>
Expects CODE to be an Emacs lisp expression that produces a
keycode vector.
eg. `-l '(kbd "M-x help RET")'`
-L, --leader <KEYS>
Use KEYS as leader at start of keyboard macro.
Defaults to `SPC` in Spacemacs and DOOM Emacs.
Can also be used to remove the leader, eg:
`SPC -L '' M-x doctor RET`
-W, --wrapper <WRAPPER>
Wrap the keyboard macro invocation inside custom lisp.
The WRAPPER code must include a `(SPC_MACRO)` lisp FORM
that will be replaced with the actual macro invocation.
This option allows you to eg, select a custom buffer or
doing anything special before/after the kbd macro is sent.
eg. `-W '(message "%s" (quote (SPC_MACRO)))'` will just echo
the generated code inside Emacs and actually do nothing.
-WPRINT
A predefined WRAPPER that prints the current buffer text.
eg. in DOOM Emacs the following command will print the ORG
agenda headlines matching "standup":
`SPC oAM standup RET -WPRINT`
-M, --macro-caller <MACRO_CALLER>
Custom Emacs lisp code that executes a keyboard macro.
The MACRO_CALLER code must include a `(SPC_KEYS)`
lisp FORM that will be replaced with the actual
keys vector.
By default it uses `(execute-kbd-macro (SPC_KEYS))`
but can be overriden to and not evaluate the keys at all.
eg. `-M '(key-description (SPC_KEYS))'` just prints the
keysequence that Emacs received.
--dry-run
Just print the emacsclient command that would be run.
-h, --help
Show this help and exit.
--
Stop parsing arguments.
All remaining arguments are given directly to the
emacsclient command.
ENVIRONMENT VARIABLES
SPC_LEADER The leader key used for sending keychords.
Defaults to `SPC` on both Spacemacs and DOOM Emacs.
SPC_WRAPPER Equivalent to always using a `--wrapper` option.
SPC_MACRO_CALLER Equivalent to always using a `--macro-caller` option.
SPC_CLIENT_CMD The command used to send emacslisp code.
It must at least support the `--eval LISP` option.
Defaults to `emacsclient`
SPC_CLIENT_OPTS Additional options for emacsclient.
See `emacsclient --help`.
For example, setting this to `--tty` will
tell emacsclient to always use the terminal UI.
EXAMPLES
# Describe what `SPC f f` does
SPC -D ff # => SPC f f runs the command counsel-find-file
# Remove leader, describe `M-x`
SPC -L '' -D M-x # => M-x runs the command counsel-M-x
# find file in remote Emacs and go to 10th line
SPC ff -r "$PWD/README.md" RET 10 gg
# open Magit rebase interactive in current terminal
SPC g/ri -- --tty
# on DOOM Emacs: create a new ORG Agenda TODO and download an attached URL
SPC Xt C-c C-a u -r "https://example.org" RET -r "Checkout this website" RET C-c C-c
# on DOOM Emacs: open an scratch buffer and pretty-print as json to the terminal
SPC bXi -f some.json ESC -r ':(json-pretty-print-buffer)' RET -WPRINT
REPORTING ISSUES
See https://github.com/vic/SPC for issues, usage examples, integrations and
contributing awesome ideas on how to use SPC to control Emacs from the terminal.
Made with <33 by vic <http://twitter.com/oeiuwq>
Of course the potential of SPC depends on your daily workflow, the tooling
provided by your Emacs configuration (be it Spacemacs/DOOM or whatever)
and what external applications you might want to integrate with Emacs.
Feel free to contribute tooling and integration tips in the Wiki
# Short command for openning files on current TTY
alias sp='env SPC_CLIENT_OPTS="--tty" command SPC'
# Visual alternative that will always create a new UI frame.
alias vsp='env SPC_CLIENT_OPTS="--create-frame" command SPC'
# Open Magit status on terminal
# mg ll # will open magit log
# mg - ie origin/main RET # rebasing with some branch
alias mg='sp gg'