API

Variable: run-command-recipes

List of functions that will produce command lists.

Some recipes ship with run-command, see run-command-load-cookbook.

Each function is called without arguments and must return a list of command specifications.

A command specification is a property list with the following properties:

  • :command-name (string, required): A name for the command, used to generate the output buffer name, as well as a fallback in case :display isn’t provided.

  • :display (string, optional): A descriptive name that will be displayed in the selector interface.

  • :command-line (string or function, required): The command line that will be executed. Can be a string or a function returning a string. A function can be used to e.g. ask the user for additional information to use in assembling a command line.

  • :working-dir (string, optional): Directory to run the command in. If not provided, defaults to default-directory.

  • :runner (function, optional): a runner function specifically for this command. If not provided, run-command-default-runner will be used.

  • :hook (function, optional): a function to run just after the command has been launched. Can be used to e.g. switch compilation-minor-mode on.

Variable: run-command-default-runner

Command runner function to use when when a command recipe does not specify one.

If nil, falls back to run-command-runner-term, except on Windows where it falls back to run-command-runner-compile.

The following runners are shipped with run-command:

  • run-command-runner-term: display command output in a term-mode buffer

  • run-command-runner-compile: display command output in a compilation-mode buffer

  • run-command-runner-vterm: display command output in a vterm buffer (requires vterm package to be available)

  • run-command-runner-eat: display command output in a eat buffer (requires eat package to be available)

Variable: run-command-selector

Interface to use to select a command.

If nil, choose one based on active global modes (such as helm-mode, ivy-mode) or fall back to completing-read.

Selectors shipped with run-command:

  • run-command-selector-completing-read: use built-in completing-read

  • run-command-selector-helm: use Helm

  • run-command-selector-ivy: use Ivy

Function: (run-command)

Display a context-sensitive list of external commands and run one.

The command list is generated by running the functions configured in run-command-recipes.

Function: (run-command-core-get-command-specs COMMAND-RECIPES)

Execute COMMAND-RECIPES functions to generate command lists.

Function: (run-command-core-run COMMAND-SPEC)

Run COMMAND-SPEC.

See run-command-recipes for the expected format of COMMAND-SPEC.

Function: (run-command-util-shorter-recipe-name-maybe COMMAND-RECIPE)

Shorten COMMAND-RECIPE name when it begins with conventional prefix.

Writing RecipesExtending