META-x

Emacs-esque M-x commands for your entire OS.

• Recommends skhd for hot-key bindings.
• Uses clipboardy for clipboard interactions.
• Uses choose for the command picker on macOS.

Support

• macOS
• Linux
• Windows

Installation

1. git clone https://github.com/calebmpeterson/META-x.git
2. cd META-x
3. yarn install

Running

Meta-x needs a hot-key launcher. skhd is recommended for macOS.

Sample .shkdrc

# ⌘SPACE to launch Meta-x on the current text selection in the active window
alt - space: EDITOR=code ~/Tools/meta-x/bin/launch
cmd - space: EDITOR=code ~/Tools/meta-x/bin/launch

# CTRL+V to launch clipboard history
ctrl - v: EDITOR=code ~/Tools/meta-x/bin/clipboard-history

Configuration

Meta-x config is kept in ~/.meta-x/ directory. This makes it easy to keep your config under source control.

Settings

All configuration options are contained in ~/.meta-x/config.json

Custom Commands

Custom commands are commonjs modules placed in ~/.meta-x/.

Example Command

To get a calculator capable of all operations/syntax available to you in JavaScript, create ~/.meta-x/calc.js with the following content:

module.exports = (selection) => eval(selection);

Non-transforming Commands

To create a command which does not transform the current selection simply return undefined from the command module's exported function:

module.exports = (selection) => {
  // Do something side-effect'ish here
  // ...

  // The current selection will not be transformed
  return undefined;
};

macOS Shortcut Commands

To run a macOS Shortcut with the output of the command:

module.exports = (selection) => {
  // The current selection will not be transformed.
  //
  // Instead, "Your Shortcut" will be run with the
  // provided input.
  return {
    shortcut: "Your Shortcut",
    input: selection.toUpperCase(),
  };
};

Command Not Found Fallback

In the event that your query does not match a known command, the raw query string will be passed to ~/.meta-x/fallback-handler.js if it exists:

module.exports = function (selection, query) {
  // Do something with the currently selected
  // text and/or the raw query string
};

Command Not Found Fallback Suggestions

The fallback-handler can provide suggestions:

module.exports = (selection, query) => {
  // Do something with the currently selected
  // text and/or the raw query string
};

module.exports.suggestions = () => {
  // The suggestions should be an array of strings
  return ["suggestion one", "suggestion two", "suggestion three"];
};

Command Context

In addition to the selection, each command function is invoked within the "command context".

The "command context" API includes:

• _ the Lodash library
• open API ↗
• get/put/post/patch/delete methods from axios ↗
• $/execa methods from execa
• osascript method from 'run-applescript`
• ENV which is loaded from the ~/.meta-x/.env file if it exists
• choose(['option A', 'option B', 'option C']) which returns a Promise that resolves to the selected option or undefined if nothing was selected.

Using NPM Packages

You can use npm packages by simply installing them in your ~/.meta-x/ directory.

For example:

> cd ~/.meta-x/
> yarn add lodash

License

Meta-x is released under the MIT license.

Contributing

Issues and Pull Requests are welcome!

Roadmap

• Configurable hot-key
• Document usage instructions
• Add built-in commands
• Document installation instructions
• Improve UI performance (with choose on macOS and dmenu on Linux)
• Periodically re-build command catalog in the background rather than re-building when launched
• Add shutdown/restart commands