1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176# bash-dash (Beta)
(Slash) Dash commands are commands typed in the command line to run an action. bash-dash is a project created for [n8n.io](https://n8n.io) workflows, but you can use it with anything that can receive HTTP requests.
## Installation
To use bash-dash, you need to have [curl](https://curl.se/) installed. Then, install bash-dash by running:
```bash
mkdir ~/.bash-dash && curl https://raw.githubusercontent.com/n8n-io/bash-dash/main/bash-dash.sh -o ~/.bash-dash/bash-dash.sh && chmod 711 ~/.bash-dash/bash-dash.sh && curl https://raw.githubusercontent.com/n8n-io/bash-dash/main/commands.sh -o ~/.bash-dash/commands.sh && echo "alias -- -=~/.bash-dash/bash-dash.sh" >> ~/.bashrc
```
bash-dash requires bash version 4+. Unfortunately does MacOS ship with the outdated bash version 3 (last patch is from 2006). We **highly** recommend upgrading it.
[How to upgrade Bash on MacOS](#Upgrade-Bash-on-MacOS)
## Usage
After installing bash-dash, you can test it and add your own custom commands.
### Update command
We are continuously improving the bash-dash. To update to the latest version, run:
```
- --update
```
### Call commands
To call a bash-dash command, type a dash `-` followed by the command you want.
For example, a `weather` command is invoked like this:
```bash
- weather
```
You can supply additional parameters by typing them after the command. For example, to get the weather in Berlin, run:
```bash
- weather berlin
```
bash-dash comes with a pre-specified test command. You can try it out by running:
```bash
- test
```
### Custom commands
You can create custom bash-dash commands for your personal use-cases. To do this, open the file `~/.bash-dash/commands.sh` and add a new line to the `commands` array. There are two possible formats in which you can add new commands, depending on how specific you need them to be: simple format and advanced format.
#### Simple Format
Add a new command by specifying the name of your custom command and the URL that should be called when the command is issued. The command will then make a GET request (by default) to that URL. Custom commands in simple format look like this:
```bash
commands[command_name]="YOUR_URL"
```
#### Advanced Format
If you want more control over your custom commands, use the advanced format, which allows you to specify three parameters:
- URL[required]: The URL that the bash-command should call
- METHOD[optional]: The HTTP Request-Method (default: GET)
- TEST-URL[optional]: The Test-URL to use (default: as described under "Call a test Webhook")
For example, to add the `test` command, type:
```bash
commands[test]="URL:http://localhost:5678/webhook/test|METHOD:GET|TEST-URL:http://localhost:5678/webhook-test/test"
```
### Response formatting
You can format how the response gets displayed in the terminal by using backslash escapes `\`.
For example, to display the word "green" in green color, type:
```bash
The following text is \033[32mgreen\033[0m
```
If you use bash-dash with n8n workflows, you can edit the displayed text in the Response node. For example, could the bash-dash-weather workflow display the output like this:
You can find the different codes for colors and formatting options (e.g., bold, underline) [here](https://misc.flogisoft.com/bash/tip_colors_and_formatting).
### Call a test Webhook
You can call a test webhook by adding `--test` as the last parameter of a command. The command will then call the URL that was defined as `TEST-URL`. If a test webhook has not been defined, the command will replace `/webhook/` with `/webhook-test/` in the URL.
## Examples
There are many possible use-cases of bash-dash. To give you some ideas, here are some examples of n8n workflows:
- `- weather berlin` to return the current weather in Berlin. You can find the workflow [here](https://n8n.io/workflows/986).
- `- asana My new task` to create a new task in Asana. You can find the workflow [here](https://n8n.io/workflows/987).
- `- sms wife Will be home late` to send a messge to your partner
- `- serverStats production1` to return server statistics
- `- spotify next` to skip to the next song on Spotify
- `- light` to toggle your IoT light
## Backend
You can use bash-dash with anything that can receive HTTP request calls.
The requests that bash-dash makes are by default GET-requests. Optional call-commands that are supplied will be sent as query parameters. The server has at least 2 minutes to send a response, which is then printed in the terminal.
## Upgrade Bash on MacOS
Unfortunately MacOS doesn’t provide the latest bash version which may prevent you to take advantage of the latest features that came with bash 4 and 5. Also, running an outdated bash version probably exposes you to some major vulnerabilities.
MacOS comes with Bash version 3 which is quite limiting and lack key features like the bash associative arrays, improved auto-completion, better Posix conformance, etc.
Follow these steps to upgrade:
### Let's check your version first
```bash
$ bash --version
3.2.53(1)-release
```
### Install Homebrew if you don't have it yet
```bash
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
### Install latest bash version
```bash
$ brew update && brew install bash
```
### Add new bash version to $PATH
If you run:
```bash
$ which bash
```
It will show you most likely, `/bin/bash`. You might want to add the new bash to your path by editing the `~/.bashrc` or `~/.bash_profile` files, by adding the following line:
```bash
# add to .bash_profile (recommended) or .bashrc
export PATH="/usr/local/bin:$PATH"
```
Now `$ which bash` should give you the Homebrew installation: `/usr/local/bin/bash`. If not, refresh your terminal session or run `$ source ~/.bash_profile` or `$ source ~/.bashrc` and try again.
### Configure terminal to use it
```bash
$ sudo bash -c 'echo /usr/local/bin/bash >> /etc/shells'
```
if you are using bash as your main shell (you can check via `$ echo $SHELL` if this prints `/bin/bash` you do) you should change to the updated version:
```bash
$ chsh -s /usr/local/bin/bash
```
Now close/refresh you terminal session.
That's it! you can check which bash version you are running via: `$ bash --version`
## License
bash-dash is [**Apache 2.0**](https://github.com/n8n-io/bash-dash/blob/main/LICENSE) licensed.