{"id":16318587,"url":"https://github.com/vic/spc","last_synced_at":"2025-10-31T12:30:27.331Z","repository":{"id":66386375,"uuid":"387579498","full_name":"vic/SPC","owner":"vic","description":"Send keyboard macros to Spacemacs or DOOM Emacs via emacsclient.","archived":false,"fork":false,"pushed_at":"2023-08-23T06:29:18.000Z","size":39,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-12-25T12:26:06.604Z","etag":null,"topics":["application-integration","doom-emacs","emacs","keyboard-macro","keyboard-shortcuts","leader-key","shell","shell-command","spacemacs"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vic.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":"2021-07-19T19:57:49.000Z","updated_at":"2024-11-29T12:50:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"bf0c8a9b-66f1-4155-9f51-22288071e02e","html_url":"https://github.com/vic/SPC","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vic%2FSPC","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vic%2FSPC/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vic%2FSPC/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vic%2FSPC/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vic","download_url":"https://codeload.github.com/vic/SPC/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239195477,"owners_count":19598036,"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":["application-integration","doom-emacs","emacs","keyboard-macro","keyboard-shortcuts","leader-key","shell","shell-command","spacemacs"],"created_at":"2024-10-10T22:24:01.889Z","updated_at":"2025-10-31T12:30:24.674Z","avatar_url":"https://github.com/vic.png","language":"Shell","readme":"# SPC\n\nAn utility for sending keyboard macros to [Spacemacs](https://www.spacemacs.org/) or [DOOM Emacs](https://github.com/hlissner/doom-emacs) via emacsclient.\n\n`SPC` was [born](https://github.com/vic/vix/blob/c55260f9591c7b243145fbbab37d68e775783a8d/vix/modules/vic/emacs/default.nix#L49) as an integration utility to make other applications interact with DOOM/Spacemacs by sending keystrokes.\n\nFor example, you can instruct iTerm2 to open a file on click by giving it the following\nSpacemacs macro using evil commands:\n\n```bash\nSPC ff -r \"$FILE\" \"$LINE\" gg \"$COL\" l\n```\n\nUsing `SPC` you can make your life on the terminal a bit more comfortable and automate\nsome things that can invoke Emacs macros. eg. creating ORG Agenda entries or using Magit.\n\n`SPC` is not limited to be used by DOOM/Spacemacs, it is handy as well on any Emacs\nconfiguration and will happily send any keyboard macro from the terminal into Emacs\njust as if you would have typed it.\n\n### Installation\n\nJust download `bin/SPC` and place it somewhere in your `PATH`.\nIt will need basic coreutils and `base64` command for sending raw inputs.\n\nThis repo is Nix enabled and can be run using: \n\n```\nnix run github:vic/SPC -- --help\n```\n\nSome people might also want to create several command aliases to ease frequent use\ncases. See the [Integrations] section.\n\n\n### Usage\n\n`SPC` expects an Emacs daemon to be already running and ready to receive keyboard macros.\nYou can start such a daemon manually within Emacs by executing `M-x server-start`.\n\nThere are many options that let you customize how `SPC` talks to your Emacs daemon.\nRunning `SPC --help` shows the command usage, included here for reference:\n\n\n\u003c!--BEGIN_HELP--\u003e\n\n```\nSPC - Send a SPC keyboard macro to Spacemacs or DOOM Emacs via emacsclient.\n\nUSAGE\n\n  SPC [OPTION..] [KEYS..] [-- emacsclient options]\n\nKEYS are key sequence strings in the format accepted by `(kbd)` and as\nreturned by commands such as `C-h k` in Emacs.\n\n\nOPTIONS\n\n  -D, --describe\n                      Causes emacs to print a brief description of the received\n                      key sequence. This option is useful when debugging or\n                      constructing your first keyboard macro.\n\n  -r, --raw \u003cINPUT\u003e\n                      Sends INPUT as if it was directly typed on Emacs.\n                      Since raw inputs can be any byte sequence they are encoded\n                      using the `base64` command and decoded on the Emacs daemon.\n\n                      This is useful for sending keys that otherwise would be\n                      interpreted as options for SPC itself.\n\n                      eg. `-r --lisp` will send `(kbd \"- - l i s p\")` to Emacs.\n\n  -f, --file-raw \u003cFILE\u003e\n                      Sends all content from FILE as if directly typed on Emacs.\n\n  -f-, --stdin\n                      Sends all content from STDIN as if directly typed on Emacs.\n\n  -l, --lisp \u003cCODE\u003e\n                      Expects CODE to be an Emacs lisp expression that produces a\n                      keycode vector.\n\n                      eg. `-l '(kbd \"M-x help RET\")'`\n\n  -L, --leader \u003cKEYS\u003e\n                      Use KEYS as leader at start of keyboard macro.\n                      Defaults to `SPC` in Spacemacs and DOOM Emacs.\n\n                      Can also be used to remove the leader, eg:\n                      `SPC -L '' M-x doctor RET`\n\n  -W, --wrapper \u003cWRAPPER\u003e\n                      Wrap the keyboard macro invocation inside custom lisp.\n                      The WRAPPER code must include a `(SPC_MACRO)` lisp FORM\n                      that will be replaced with the actual macro invocation.\n\n                      This option allows you to eg, select a custom buffer or\n                      doing anything special before/after the kbd macro is sent.\n\n                      eg. `-W '(message \"%s\" (quote (SPC_MACRO)))'` will just echo\n                      the generated code inside Emacs and actually do nothing.\n\n  -WPRINT\n                      A predefined WRAPPER that prints the current buffer text.\n\n                      eg. in DOOM Emacs the following command will print the ORG\n                          agenda headlines matching \"standup\":\n                      `SPC oAM standup RET -WPRINT`\n\n\n\n  -M, --macro-caller \u003cMACRO_CALLER\u003e\n                      Custom Emacs lisp code that executes a keyboard macro.\n                      The MACRO_CALLER code must include a `(SPC_KEYS)`\n                      lisp FORM that will be replaced with the actual\n                      keys vector.\n\n                      By default it uses `(execute-kbd-macro (SPC_KEYS))`\n                      but can be overriden to and not evaluate the keys at all.\n\n                      eg. `-M '(key-description (SPC_KEYS))'` just prints the\n                      keysequence that Emacs received.\n\n  --dry-run\n                      Just print the emacsclient command that would be run.\n\n  -h, --help\n                      Show this help and exit.\n\n  --\n                      Stop parsing arguments.\n                      All remaining arguments are given directly to the\n                      emacsclient command.\n\n\n\nENVIRONMENT VARIABLES\n\n  SPC_LEADER          The leader key used for sending keychords.\n\n                      Defaults to `SPC` on both Spacemacs and DOOM Emacs.\n\n  SPC_WRAPPER         Equivalent to always using a `--wrapper` option.\n\n  SPC_MACRO_CALLER    Equivalent to always using a `--macro-caller` option.\n\n  SPC_CLIENT_CMD      The command used to send emacslisp code.\n                      It must at least support the `--eval LISP` option.\n\n                      Defaults to `emacsclient`\n\n  SPC_CLIENT_OPTS     Additional options for emacsclient.\n                      See `emacsclient --help`.\n\n                      For example, setting this to `--tty` will\n                      tell emacsclient to always use the terminal UI.\n\nEXAMPLES\n\n  # Describe what `SPC f f` does\n  SPC -D ff          # =\u003e SPC f f runs the command counsel-find-file\n\n  # Remove leader, describe `M-x`\n  SPC -L '' -D M-x   # =\u003e M-x runs the command counsel-M-x\n\n  # find file in remote Emacs and go to 10th line\n  SPC ff -r \"$PWD/README.md\" RET 10 gg\n\n  # open Magit rebase interactive in current terminal\n  SPC g/ri -- --tty\n\n  # on DOOM Emacs: create a new ORG Agenda TODO and download an attached URL\n  SPC Xt C-c C-a u -r \"https://example.org\" RET -r \"Checkout this website\" RET C-c C-c\n\n  # on DOOM Emacs: open an scratch buffer and pretty-print as json to the terminal\n  SPC bXi -f some.json ESC -r ':(json-pretty-print-buffer)' RET -WPRINT\n\n\nREPORTING ISSUES\n\nSee https://github.com/vic/SPC for issues, usage examples, integrations and\ncontributing awesome ideas on how to use SPC to control Emacs from the terminal.\n\nMade with \u003c33 by vic \u003chttp://twitter.com/oeiuwq\u003e\n```\n\u003c!--END_HELP--\u003e\n\n\n\n## Integrations\n\nOf course the potential of `SPC` depends on your daily workflow, the tooling\nprovided by your Emacs configuration (be it Spacemacs/DOOM or whatever)\nand what external applications you might want to integrate with Emacs.\n\nFeel free to contribute tooling and integration tips in the [Wiki](wiki)\n\n#### Suggested shell aliases\n\n```shell\n# Short command for openning files on current TTY\nalias sp='env SPC_CLIENT_OPTS=\"--tty\" command SPC'\n\n# Visual alternative that will always create a new UI frame.\nalias vsp='env SPC_CLIENT_OPTS=\"--create-frame\" command SPC'\n\n# Open Magit status on terminal\n# mg ll                    # will open magit log\n# mg - ie origin/main RET  # rebasing with some branch\nalias mg='sp gg'\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvic%2Fspc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvic%2Fspc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvic%2Fspc/lists"}