How to define shell commands - Shell commands documentation

## Creating your first command 1. After you have [installed the *Shell commands* plugin](https://github.com/Taitava/obsidian-shellcommands#installation--usage), open up the settings modal and select *Shell commands* from the left side menu: ![[Settings-menu.png]] 2. You'll see an empty list of shell commands: ![[Settings-main-no-shell-commands.png]] 3. Click on the *New command* button. An empty shell command will appear: ![[Settings-main-new-shell-command.png]] 4. Type a shell command to the *Enter your command* text field. You can use [[Example shell commands|some example shell commands]]. 5. Settings are immediately saved when changes are made. > [!Tip] Multiline shell commands > - You can hit the enter key in all shell command fields to make them grow in height. > - Shells interpret each line as their own command, just like in script files, so a line following another is not concatenated to the previous line. Example: > ```bash > cd MyFolder > mkdir NewSubFolder > ``` > Each line forms a new command, but they are executed during the same process, i.e. in one go. > - By default, shell command fields' maximum height is not limited, but you can use the [[Hidden settings#^max-visible-lines-in-shell-command-fields|`max_visible_lines_in_shell_command_fields` hidden setting]] to limit it. It won't restrict adding more lines to a shell command, it just makes the field to have a scroll bar instead of stretching infinitely. ## Main controls for shell commands ^shell-command-controls ![[Settings-main-new-shell-command.png]] In addition to the actual shell command text field, there are some other controls in the picture above: - *Command #0* is just a serial number for the shell command. You can replace this text with an [[alias]]. - <svg viewBox="0 0 100 100" class="run-command" width="16" height="16"><path fill="currentColor" stroke="currentColor" d="M37,16c-4.4,0-8.3,3.3-9.2,7.6l-11.6,52c-0.5,2.2,0,4.3,1.2,5.9c1.2,1.6,3.2,2.6,5.4,2.6H79c4.4,0,8.3-3.3,9.2-7.6 l11.6-52c0.5-2.2,0-4.3-1.2-5.9C97.4,17,95.4,16,93.2,16L37,16z M37,20h56.2c1.1,0,1.8,0.4,2.2,1c0.5,0.6,0.7,1.4,0.4,2.6l-1,4.4 H30.8l0.8-3.6C32.1,22.2,34.8,20,37,20z M29.9,32H94l-9.6,43.6C83.9,77.8,81.2,80,79,80H22.8c-1.1,0-1.8-0.4-2.2-1 c-0.5-0.6-0.7-1.4-0.4-2.6L29.9,32z M0,36v4h19.6l0.9-4L0,36z M36.7,38c-0.8,0.1-1.4,0.7-1.6,1.5l-3.5,14c-0.2,0.6,0,1.2,0.4,1.7 c0.4,0.5,1,0.8,1.6,0.8H81c0.9,0,1.7-0.6,1.9-1.5l3.5-14c0.2-0.6,0-1.3-0.4-1.8c-0.4-0.5-1-0.8-1.6-0.8H37.1c-0.1,0-0.1,0-0.2,0 C36.9,38,36.8,38,36.7,38L36.7,38z M38.7,42h43.2l-2.4,10H36.2L38.7,42z M0,52v4h16l0.9-4H0z M0,68v4h12.4l0.9-4H0z"></path></svg> *Execute now*: A quick way to test your shell command right away. If you hold down Ctrl/Cmd key while clicking, all output will be shown in the [[Output channel - Ask after execution|Ask after execution]] modal, which might be handy for temporarily inspecting output. - <svg viewBox="0 0 100 100" class="gear" width="16" height="16"><path fill="currentColor" stroke="currentColor" d="M44.4,4c-1,0-1.8,0.7-2,1.7l-1.9,11.9c-2.3,0.7-4.6,1.6-6.7,2.7l-9.8-7c-0.8-0.6-1.9-0.5-2.6,0.2l-7.8,7.8 c-0.7,0.7-0.8,1.8-0.2,2.6l6.9,9.9c-1.2,2.1-2.1,4.4-2.8,6.7l-11.9,2c-1,0.2-1.7,1-1.7,2v11c0,1,0.7,1.8,1.6,2l11.9,2.1 c0.7,2.4,1.6,4.6,2.8,6.7l-7,9.8c-0.6,0.8-0.5,1.9,0.2,2.6l7.8,7.8c0.7,0.7,1.8,0.8,2.6,0.2l9.9-6.9c2.1,1.2,4.3,2.1,6.7,2.8 l2,11.9c0.2,1,1,1.7,2,1.7h11c1,0,1.8-0.7,2-1.7l2.1-12c2.3-0.7,4.6-1.6,6.7-2.8l10,7c0.8,0.6,1.9,0.5,2.6-0.2l7.8-7.8 c0.7-0.7,0.8-1.8,0.2-2.6l-7.1-9.9c1.1-2.1,2.1-4.3,2.7-6.6l12-2.1c1-0.2,1.7-1,1.7-2v-11c0-1-0.7-1.8-1.7-2l-12-2 c-0.7-2.3-1.6-4.5-2.7-6.6l7-10c0.6-0.8,0.5-1.9-0.2-2.6l-7.8-7.8c-0.7-0.7-1.8-0.8-2.6-0.2l-9.8,7.1c-2.1-1.2-4.3-2.1-6.7-2.8 l-2.1-12c-0.2-1-1-1.7-2-1.7L44.4,4z M46.1,8h7.6l2,11.4c0.1,0.8,0.7,1.4,1.5,1.6c2.9,0.7,5.7,1.9,8.2,3.4 c0.7,0.4,1.6,0.4,2.2-0.1l9.4-6.7l5.4,5.4l-6.7,9.5c-0.5,0.6-0.5,1.5-0.1,2.2c1.5,2.5,2.6,5.2,3.4,8.1c0.2,0.8,0.8,1.4,1.6,1.5 L92,46.1v7.6l-11.4,2c-0.8,0.1-1.4,0.7-1.6,1.5c-0.7,2.9-1.9,5.6-3.4,8.1c-0.4,0.7-0.4,1.6,0.1,2.2l6.8,9.4l-5.4,5.4l-9.5-6.7 c-0.7-0.5-1.5-0.5-2.2-0.1c-2.5,1.5-5.2,2.7-8.2,3.4c-0.8,0.2-1.3,0.8-1.5,1.6l-2,11.4h-7.6l-1.9-11.3c-0.1-0.8-0.7-1.4-1.5-1.6 c-2.9-0.7-5.7-1.9-8.2-3.4c-0.7-0.4-1.5-0.4-2.2,0.1l-9.4,6.6l-5.4-5.4l6.6-9.3c0.5-0.7,0.5-1.5,0.1-2.2c-1.5-2.5-2.7-5.3-3.4-8.2 c-0.2-0.8-0.8-1.3-1.6-1.5L8,53.7v-7.6l11.3-1.9c0.8-0.1,1.4-0.7,1.6-1.5c0.7-2.9,1.9-5.7,3.4-8.2c0.4-0.7,0.4-1.5-0.1-2.2 l-6.6-9.4l5.4-5.4l9.3,6.7c0.6,0.5,1.5,0.5,2.2,0.1c2.5-1.5,5.3-2.7,8.2-3.4c0.8-0.2,1.4-0.8,1.5-1.6L46.1,8z M50,34 c-8.8,0-16,7.2-16,16s7.2,16,16,16s16-7.2,16-16S58.8,34,50,34z M50,38c6.7,0,12,5.3,12,12s-5.3,12-12,12s-12-5.3-12-12 S43.3,38,50,38z"></path></svg> *Alias, Icon, Confirmation*: Allows you to define an [[alias]] and menu icon for the shell command; and enable a confirmation question to be asked every time before execution. - <svg viewBox="0 0 100 100" class="note-glyph" width="16" height="16"><path fill="currentColor" stroke="currentColor" d="M23.3,13.3c-5.5,0-10,4.5-10,10v53.3c0,5.5,4.5,10,10,10H65c0.9,0,1.7-0.4,2.4-1l18.3-18.3c0.6-0.6,1-1.5,1-2.4V23.3 c0-5.5-4.5-10-10-10H23.3z M23.3,20h53.3c1.9,0,3.3,1.4,3.3,3.3v40H70c-3.7,0-6.7,3-6.7,6.7v10h-40c-1.9,0-3.3-1.4-3.3-3.3V23.3 C20,21.4,21.4,20,23.3,20z M33.3,36.7c-1.2,0-2.3,0.6-2.9,1.7c-0.6,1-0.6,2.3,0,3.4c0.6,1,1.7,1.7,2.9,1.7h13.3 c1.2,0,2.3-0.6,2.9-1.7c0.6-1,0.6-2.3,0-3.4c-0.6-1-1.7-1.7-2.9-1.7H33.3z M60,36.7c-1.2,0-2.3,0.6-2.9,1.7c-0.6,1-0.6,2.3,0,3.4 c0.6,1,1.7,1.7,2.9,1.7h6.7c1.2,0,2.3-0.6,2.9-1.7s0.6-2.3,0-3.4c-0.6-1-1.7-1.7-2.9-1.7H60z M33.3,50c-1.2,0-2.3,0.6-2.9,1.7 c-0.6,1-0.6,2.3,0,3.4c0.6,1,1.7,1.7,2.9,1.7H60c1.2,0,2.3-0.6,2.9-1.7c0.6-1,0.6-2.3,0-3.4S61.2,50,60,50H33.3z"></path></svg> *Preactions: Prompt for asking values from user*: [[Prompts]] are customisable modals that can be defined to open up when a shell command is being executed, allowing the user to supplement values to the executable shell command. - <svg viewBox="0 0 100 100" class="lines-of-text" width="16" height="16"><path fill="currentColor" stroke="currentColor" d="M16,10c-3.3,0-6,2.7-6,6v68c0,3.3,2.7,6,6,6h68c3.3,0,6-2.7,6-6V16c0-3.3-2.7-6-6-6L16,10z M16,14h68c1.1,0,2,0.9,2,2v68 c0,1.1-0.9,2-2,2H16c-1.1,0-2-0.9-2-2V16C14,14.9,14.9,14,16,14z M22,24v4h52v-4H22z M22,36v4h34v-4L22,36z M22,48v4h52v-4H22z M22,60v4h34v-4H22z M22,72v4h52v-4H22z"></path></svg> *Stdout/stderr handling, Ignore errors*: Allows you to define [[Output channels|how the shell command's output should be processed]]; and possible [[Ignoring errors|ignoring of errors]]. - <svg viewBox="0 0 100 100" class="stacked-levels" width="16" height="16"><path fill="currentColor" stroke="currentColor" d="M12,4c-1.1,0-2,0.9-2,2v20c0,1.1,0.9,2,2,2h14v21.7c0,0.2,0,0.4,0,0.7V84c0,1.1,0.9,2,2,2h26v8c0,1.1,0.9,2,2,2h32 c1.1,0,2-0.9,2-2V74c0-1.1-0.9-2-2-2H56c-1.1,0-2,0.9-2,2v8H30V52h24v8c0,1.1,0.9,2,2,2h32c1.1,0,2-0.9,2-2V40c0-1.1-0.9-2-2-2 H56c-1.1,0-2,0.9-2,2v8H30V28h14c1.1,0,2-0.9,2-2V6c0-1.1-0.9-2-2-2L12,4z M14,8h28v16H28.3c-0.1,0-0.2,0-0.3,0 c-0.1,0-0.2,0-0.3,0H14L14,8z M58,42h28v16H58v-7.7c0-0.2,0-0.4,0-0.7V42z M58,76h28v16H58v-7.7c0-0.2,0-0.4,0-0.7V76z"></path></svg> *Shell selection, Operating system specific shell commands*: Advanced features for choosing a [[Shells|shell]] where the shell command will be executed in; and defining different versions of the shell command for different operating systems, in case you synchronize your vault between multiple OSes. - <svg viewBox="0 0 100 100" class="dice" width="16" height="16"><path fill="currentColor" stroke="currentColor" d="M27,4c-4.5,0-8.6,2.4-10.6,6.5c0,0,0,0-0.1,0.1L9.8,23.1c0,0.1,0,0.2-0.1,0.3c0,0,0,0-0.1,0.1c0,0,0,0,0,0.1 C8.6,25.4,8,27.6,8,30v52c0,7.7,6.3,14,14,14h56c7.7,0,14-6.3,14-14V30c0-2.4-0.6-4.5-1.6-6.5c0-0.2-0.1-0.4-0.2-0.6l-6.6-12.6 c0,0,0,0,0-0.1h-0.1C81.5,6.4,77.5,4,73,4L27,4z M27,8h46c3.1,0,5.8,1.6,7,4.1l2.4,4.6C81,16.3,79.6,16,78,16H22 c-1.5,0-2.9,0.2-4.3,0.7l2.3-4.4c0,0,0,0,0-0.1C21.3,9.6,23.9,8,27,8z M51.2,9.9c-1.5,0-2.9,0.1-4,0.4c-1.8,0.6-2,1.2-2,1.6 c0,0.4,0.2,1.2,2,1.6c1.2,0.2,2.6,0.4,4,0.4c1.6,0,3-0.2,4-0.4c1.8-0.6,2-1.2,2-1.6c0-0.4-0.2-1.2-2-1.6 C54.1,10.1,52.6,9.9,51.2,9.9z M22,20h56c5.5,0,10,4.5,10,10v52c0,5.5-4.5,10-10,10H22c-5.5,0-10-4.5-10-10V30 C12,24.5,16.5,20,22,20z M68,32c-3.3,0-6,2.7-6,6s2.7,6,6,6s6-2.7,6-6S71.3,32,68,32z M50,50c-3.3,0-6,2.7-6,6s2.7,6,6,6 s6-2.7,6-6S53.3,50,50,50z M32,68c-3.3,0-6,2.7-6,6c0,3.3,2.7,6,6,6s6-2.7,6-6C38,70.7,35.3,68,32,68z"></path></svg> *Events*: Here you can define a shell command to be executed automatically in specific situations, e.g. when you switch to a different file in the editor. [[Events - general principles|Read more about events]]. - <svg viewBox="0 0 100 100" class="code-glyph" width="16" height="16"><path fill="currentColor" stroke="currentColor" d="M56.6,13.3c-1.6,0-2.9,1.2-3.2,2.7L40.1,82.7c-0.3,1.2,0.1,2.4,1,3.2c0.9,0.8,2.2,1.1,3.3,0.7c1.1-0.4,2-1.4,2.2-2.6 l13.3-66.7c0.2-1,0-2-0.7-2.8S57.6,13.3,56.6,13.3z M24.2,26.6c-1.1,0-2.1,0.5-2.8,1.4l-14.1,20c-0.8,1.2-0.8,2.7,0,3.9l14.1,20 c1.1,1.5,3.1,1.9,4.6,0.8c1.5-1.1,1.9-3.1,0.8-4.6L14.1,50l12.8-18.1c0.7-1,0.8-2.4,0.3-3.5C26.6,27.3,25.4,26.6,24.2,26.6 L24.2,26.6z M76.5,26.6c-1.2,0-2.4,0.8-2.9,1.9c-0.5,1.1-0.4,2.4,0.3,3.4L86.7,50L73.9,68.1c-0.7,1-0.8,2.2-0.3,3.3 s1.5,1.8,2.7,1.9c1.2,0.1,2.3-0.4,3-1.4l14.1-20c0.8-1.2,0.8-2.7,0-3.9l-14.1-20C78.7,27.1,77.7,26.6,76.5,26.6L76.5,26.6z"></path></svg> *Default values for variables*: Certain variables are not available in some situations. Normally, they show an error message and prevent execution if they are unavailable, but you can define alternative values that can substitute variables when they are unavailable. [[Default values|Read more about default values]]. - <svg viewBox="0 0 100 100" class="trash" width="16" height="16"><path fill="currentColor" stroke="currentColor" stroke-width="2" d="M42,4c-3.3,0-6,2.7-6,6v4H20.3c-0.1,0-0.2,0-0.3,0c-0.1,0-0.2,0-0.3,0H16c-0.7,0-1.4,0.4-1.8,1c-0.4,0.6-0.4,1.4,0,2 c0.4,0.6,1,1,1.8,1h2v72c0,3.3,2.7,6,6,6h52c3.3,0,6-2.7,6-6V18h2c0.7,0,1.4-0.4,1.8-1c0.4-0.6,0.4-1.4,0-2c-0.4-0.6-1-1-1.8-1 h-3.7c-0.2,0-0.4,0-0.7,0H64v-4c0-3.3-2.7-6-6-6L42,4z M42,8h16c1.1,0,2,0.9,2,2v4H40v-4C40,8.9,40.9,8,42,8z M22,18h15.7 c0.2,0,0.4,0,0.7,0h23.3c0.2,0,0.4,0,0.7,0H78v72c0,1.1-0.9,2-2,2H24c-1.1,0-2-0.9-2-2V18z M38,28c-1.1,0-2,0.9-2,2v50 c0,0.7,0.4,1.4,1,1.8s1.4,0.4,2,0s1-1,1-1.8V30c0-0.5-0.2-1.1-0.6-1.4C39,28.2,38.5,28,38,28z M50,28c-1.1,0-2,0.9-2,2v50 c0,0.7,0.4,1.4,1,1.8c0.6,0.4,1.4,0.4,2,0s1-1,1-1.8V30c0-0.5-0.2-1.1-0.6-1.4C51,28.2,50.5,28,50,28z M62,28c-1.1,0-2,0.9-2,2v50 c0,0.7,0.4,1.4,1,1.8c0.6,0.4,1.4,0.4,2,0s1-1,1-1.8V30c0-0.5-0.2-1.1-0.6-1.4C63,28.2,62.5,28,62,28z"></path></svg> *Delete this shell command*. Will ask a confirmation. Deletion cannot be undone, unless you have [[Settings backups|backups of the plugin's settings]]. # History - [0.14.0 - 2022-07-22](https://github.com/Taitava/obsidian-shellcommands/blob/main/CHANGELOG.md#0140---2022-07-22): <small>This page was last modified on <strong>2022-07-23</strong> and created on 2021-11-25. <a href="https://github.com/Taitava/obsidian-shellcommands-documentation/commits/main/./Basic%20usage/How%20to%20define%20shell%20commands.md">See page edit history</a>.</small> - The *Execute now* button can now be `Ctrl`/`Cmd` + clicked to temporarily show all output in a modal ([#241](https://github.com/Taitava/obsidian-shellcommands/issues/241)). - The ability to define menu icons was released ([#240](https://github.com/Taitava/obsidian-shellcommands/issues/240)). - [0.13.0 - 2022-06-28](https://github.com/Taitava/obsidian-shellcommands/blob/main/CHANGELOG.md#0130---2022-06-28): - Support for multiline shell commands was added ([#203](https://github.com/Taitava/obsidian-shellcommands/issues/203)). - Icon button for adding/changing hotkeys was added ([#210](https://github.com/Taitava/obsidian-shellcommands/issues/210)). - [0.12.0 - 2022-05-07](https://github.com/Taitava/obsidian-shellcommands/blob/main/CHANGELOG.md#0120---2022-05-07): - *Preactions* were added ([#37](https://github.com/Taitava/obsidian-shellcommands/issues/37)). - *Default values for variables* support was added ([#190](https://github.com/Taitava/obsidian-shellcommands/issues/190)). - [0.10.0 - 2022-02-06](https://github.com/Taitava/obsidian-shellcommands/blob/main/CHANGELOG.md#0100---2022-02-06): *Events* were added ([#123](https://github.com/Taitava/obsidian-shellcommands/issues/123)). - [0.8.0 - 2021-12-10](https://github.com/Taitava/obsidian-shellcommands/blob/main/CHANGELOG.md#080---2021-12-10): Variable instructions were moved to a separate tab *Variables* ([#110](https://github.com/Taitava/obsidian-shellcommands/issues/110)). - [0.7.0 - 2021-11-25](https://github.com/Taitava/obsidian-shellcommands/blob/main/CHANGELOG.md#070---2021-11-25): Settings were split to tabs ([#78](https://github.com/Taitava/obsidian-shellcommands/issues/78) and [#85](https://github.com/Taitava/obsidian-shellcommands/issues/85)). - [0.4.0 - 2021-09-26](https://github.com/Taitava/obsidian-shellcommands/blob/main/CHANGELOG.md#040---2021-09-26): *Execute now* icon button was added ([#30](https://github.com/Taitava/obsidian-shellcommands/issues/30)). - [0.3.0 - 2021-09-17](https://github.com/Taitava/obsidian-shellcommands/blob/main/CHANGELOG.md#030---2021-09-17): - Shell commands are now deleted with an icon button, not by clearing a text field ([#20](https://github.com/Taitava/obsidian-shellcommands/issues/20)). - Hotkeys are displayed next to shell commands ([#21](https://github.com/Taitava/obsidian-shellcommands/issues/21)). - [0.2.0 - 2021-09-11](https://github.com/Taitava/obsidian-shellcommands/blob/main/CHANGELOG.md#020---2021-09-11): New setting *Alias* created the extra options modal for shell commands ([#6](https://github.com/Taitava/obsidian-shellcommands/issues/6)). - [0.1.0 - 2021-08-29](https://github.com/Taitava/obsidian-shellcommands/blob/main/CHANGELOG.md#010---2021-08-29): Added first built-in variables. (No issue). - [0.0.0 - 2021-08-22](https://github.com/Taitava/obsidian-shellcommands/blob/main/CHANGELOG.md#000---2021-08-22): Initial release of the plugin. (No issue). > [!page-edit-history]- Page edit history: 2021-11-25 ➔ 2022-07-23 > - [<small>2022-07-23</small>](https://github.com/Taitava/obsidian-shellcommands-documentation/commit/7595405f40dfd5f8b07b6107adae0c0ea78ca3e9): How to define shell commands.md: Add 0.14.0 history records and mention icon ability. > - [<small>2022-07-17</small>](https://github.com/Taitava/obsidian-shellcommands-documentation/commit/cb17681b184f00ad3113e0342428d3f93bcf06bb): How to define shell commands.md: Added information about ctrl/cmd clicking the 'Execute now' button. > - [<small>2022-06-28</small>](https://github.com/Taitava/obsidian-shellcommands-documentation/commit/49efe1a5a719cb695cc0a4a96d05c10548298804): 0.13.0 is released. > - [<small>2022-05-29</small>](https://github.com/Taitava/obsidian-shellcommands-documentation/commit/beb1e7a684c3f6668eecdcd53e6ab7fe9b2eca60): Multiline shell commands: Mention that the feature is only available in 0.13.0 beta. > - [<small>2022-05-12</small>](https://github.com/Taitava/obsidian-shellcommands-documentation/commit/2fabd9b7768d3301a6b467f1e8815c54cfc1978e): How to define shell commands.md: Define a date for 0.12.0. > - [<small>2022-05-03</small>](https://github.com/Taitava/obsidian-shellcommands-documentation/commit/7c9621f873ef2df46e6adb74bd2d84f678c93c13): How to define shell commands.md: Added a History section. > - [<small>2022-05-03</small>](https://github.com/Taitava/obsidian-shellcommands-documentation/commit/8e2b04d58bc91cd7d795b95217fd45c2fc11df2c): Multiline shell commands. > - [<small>2022-04-29</small>](https://github.com/Taitava/obsidian-shellcommands-documentation/commit/23784701289a0722381f22a93bd40a4ba63b4aac): How to define shell commands.md: Add icons for preactions and variable default values. > - [<small>2022-01-29</small>](https://github.com/Taitava/obsidian-shellcommands-documentation/commit/8008003191e4522eb487404fa41ffe7ed16dfd57): How to define shell commands: Add information about events. > - [<small>2022-01-02</small>](https://github.com/Taitava/obsidian-shellcommands-documentation/commit/f82d4d857c0acf39c4ffac3af84633e843e71d31): Events: General information. > - [<small>2021-11-25</small>](https://github.com/Taitava/obsidian-shellcommands-documentation/commit/97a36489865125f8a23f18bb34649420564a2f8b): How to define shell commands: Fix a link. > - [<small>2021-11-25</small>](https://github.com/Taitava/obsidian-shellcommands-documentation/commit/9873c4587a2b97c6a61a5cbfc2bb7ce55834ffda): Basic usage instructions. > > [<small>See this list of commits on GitHub</small>](https://github.com/Taitava/obsidian-shellcommands-documentation/commits/main/Basic%20usage/How%20to%20define%20shell%20commands.md). > ^page-edit-history