# Run a command

> Run a command or a script on your Mac on a schedule. A new line it prints, a new object in its JSON, or a failure reaches the notch once.

Source: https://coisland.app/docs/connect-shell/

## What you need

- **You need:** No token, from Commands run as you, on this Mac
- **The form asks:** Connector name, Folder (optional), Timeout (optional)
- **You can watch:** Output lines, JSON rows, Command fails
- **Access:** Run the command you wrote, as you, on this Mac; no shell reads it

A Shell command connector runs a command or a script on your Mac on a schedule. **Output lines** alerts on each new line it prints, **JSON rows** on each new object of the JSON array it prints, and **Command fails** when it exits with a non-zero status. Nothing leaves your Mac and nothing is kept in the Keychain.

A command runs as you, with your files, keys and network, like one you type in Terminal: only run what you wrote or trust. Opening an alert shows what was saved; it never runs the command again.

## Add a Shell command connector

1. Open **Settings › Connectors**, click **+**, choose **Shell command**.
2. **Connector name:** what monitors call it, such as `mac`.
3. **Folder:** optional, where commands run and where `./script.sh` starts; your home folder unless given.
4. **Timeout:** optional, in seconds from 1 to 600; 30 unless given. A command still running then is stopped.
5. **Test connector** runs nothing: it shows who commands run as, where, and which folders programs are found in.

## Write the command

The command is the program and its arguments, quoted as in a shell, and nothing else: no shell reads it.

- `'single quotes'` keep everything; `"double quotes"` keep everything but `\"` and `\\`; a `\` keeps the next character.
- A word starting with `~/` starts in your home folder.
- `$VARIABLES`, `*` and `?` are passed as written.
- An unquoted `|`, `&`, `;`, `<`, `>`, `` ` `` or `$(` is refused. Put a pipeline or a redirection in a script file and run the script, or write `/bin/sh -c '...'` yourself.
- A bare name like `curl` is found in Homebrew's folders, `~/.local/bin` and the system folders; your shell profile does not run.

## The three kinds

| Kind | Alerts when | A non-zero exit |
|---|---|---|
| Output lines | a line appears that was not there at the previous check | an error if it wrote to standard error, else no lines (like `grep` finding nothing) |
| JSON rows | a new object appears in the JSON array printed on standard output | as above |
| Command fails | the command starts exiting non-zero; once, until it passes again | is the alert, with what it printed |

```text
-- name: Website down
-- kind: shell.exit-code
-- connector: mac
-- every: 5m

/usr/bin/curl -fsS --max-time 10 https://example.com/health
```

A command that reads Desktop, Documents or Downloads makes macOS ask once, in CoIsland's name.

## Troubleshooting

| Message | What to do |
|---|---|
| ... is not read by a shell here | Quote it, or move the pipeline into a script |
| ... was not found | Give the program's full path, like `/usr/local/bin/tool` |
| ... could not be started | Make the script executable: `chmod +x` |
| The command was still running after 30 s | Raise the connector's timeout, or make the command faster |
| The command exited with status N: ... | What the command said on standard error |
| The command's output is not JSON | JSON rows reads a JSON array of objects on standard output |