Awesome

Write-only command-line integration for Discord webhooks, written in 100% Bash script. Influenced heavily by slack-cli.

Table of Contents

• Features
• Dependencies
• Usage
• Options
• Tips
• • Proper character escaping
• Contributing
• License

Features

• Create and send very customizable and beautiful Discord messages 🎉 ✨
• Less than 400 lines of pure Bash 😎
• Extremely lightweight ⚡ 🚀
• Only requires curl and jq to run 🔥

Dependencies

• bash (GNU Bourne-Again SHell)
• bats (tests)
• curl (http requests)
• jq (JSON parsing)
• base64 (webhook avatar modification)
• file (MIME type retrieval for webhook avatar modification)

Usage

1. Setting up a Discord webhook.

1. Setup a webhook in the desired Discord text channel
2. Download (or clone) a copy of discord.sh
3. Point discord.sh at a webhook endpoint (see below)
4. Go nuts.

2. Specifying a Webhook URL within discord.sh

There are three ways to point discord.sh at a webhook endpoint, in order of priority that discord.sh takes:

1. Pass the webhook URL as an argument to discord.sh using --webhook-url
2. Set an environment variable called $DISCORD_WEBHOOK
3. Create a file called .webhook in the same directory as discord.sh, containing only the webhook URL

3. Using the script

Simple chat example

$ ./discord.sh --webhook-url="$WEBHOOK" --text "Hello, world!"

Simple chat example with custom username and avatar

$ ./discord.sh \
  --webhook-url="$WEBHOOK" \
  --username "NotificationBot" \
  --avatar "https://i.imgur.com/12jyR5Q.png" \
  --text "Hello, world!"

Advanced chat example using an embed (using all possible options)

$ ./discord.sh \
  --webhook-url="$WEBHOOK" \
  --username "NotificationBot" \
  --avatar "https://i.imgur.com/12jyR5Q.png" \
  --text "Check out this embed!" \
  --title "New Notification!" \
  --description "This is a description\nPretty cool huh?" \
  --color "0xFFFFFF" \
  --url "https://github.com/fieu/discord.sh" \
  --author "discord.sh" \
  --author-url "https://github.com/fieu/discord.sh" \
  --author-icon "https://i.imgur.com/12jyR5Q.png" \
  --image "https://i.imgur.com/12jyR5Q.png" \
  --thumbnail "https://i.imgur.com/12jyR5Q.png" \
  --field "Author;ChaoticWeg" \
  --field "Author;fieu" \
  --footer "discord.sh" \
  --footer-icon "https://i.imgur.com/12jyR5Q.png" \
  --timestamp

Sending a file (up to 8MB, per Discord limitations)

Note: per the Discord webhook API, posts cannot contain embeds and file attachments. Therefore, discord.sh will bail out when trying to build a message with embeds and files. The best practice is to send the message with embeds before sending a file.

$ ./discord.sh \
  --webhook-url="$WEBHOOK" \
  --file README.md \
  --username "Notification Bot" \
  --text "Check out this README.md file!"

Options

• --webhook-url <url>

This should be set to your Discord webhook URL. You may alternatively set the environment variable DISCORD_WEBHOOK to your Discord webhook URL and that way you don't have to pass in the webhook URL inline.

• --text <string>

This is basic text like shown below.

• --username <string>

You can override the username of the webhook "bot" with this flag.

• --avatar <url>

You can override the avatar of the webhook "bot" with this flag.

• --modify

You can permanently change the username and avatar of the webhook. The following options are valid: --username and --modify

Warning No other options may be passed, including those for sending messages.

Example

$ ./discord.sh \
  --modify \
  --username "NotifBot" \
  --avatar "https://i.imgur.com/12jyR5Q.png" 

Once executed, all other webhook messages by default will contain the username and avatar set.

Advanced Options

Now we're going to look at how to setup a custom embed message.

• --title <string>

This option allows you to set the title of the embed.

• --description <string>

This option allows you to set the description of the embed.

• --color <string>

This option allows you to set color on the left of the embed.

Input Syntax 1: 0x + COLOR HEX

Input Syntax 2: COLOR DEC

Input Example 1: --color 0xFFFFFF

Input Example 2: --color 16777215

• --url <url>

This option allows you to set the URL of the --title flag within the embed.

• --author <string>

This option allows you to set the author name of the embed.

• --author-url <url>

This option allows you to set the author URL of the --author flag within the embed.

• --author-icon <url>

This option allows you to set the author icon that sits to the left of the --author flag within the embed.

• --image <url>

This option allows you to set the image that sits within the embed.

• --thumbnail <url>

This option allows you to set the thumbnail that sits to the right within the embed.

• --field <name;value;inline>

This option allows you to add fields to your embed. You may use this option multiple times up to 25 times. Example usage:

$ ./discord.sh \
  --webhook-url="$WEBHOOK" \
  --username "System Status" \
  --description "Here are your system stats!" \
  --field "Hostname;localhost;false" \
  --field "CPU;95%" \
  --field "Disk Usage;120/512GB"

• --footer <string>

This option allows you to set the thumbnail that sits to the right within the embed.

• --footer-icon <url>

This option allows you to set the footer icon that sites to the right of the --footer flag within the embed.

• --timestamp

This option allows you to define whether the timestamp is displayed on the embed message or not.

Tips

Proper character escaping

If you want to show the output of a file or stdin via discord.sh, and your file includes special characters such as backticks (`) and ", then you can't simply cat filename. You will need to properly escape special characters.

One of the easiest methods to output properly escaped text from a file is to use jq, cut, and rev

Prerequisites

• jq - Character escaping
• cut - Cut characters from string (part of coreutils, included by default on most systems)
• rev - Reversing of characters (part of util-linux, included by default on most systems)

Usage (contents of file)

1. Simply pass filename to the following command to escape the file contents to stdout:

jq -Rs . <filename | cut -c 2- | rev | cut -c 2- | rev

Usage (contents of stdin)

1. Simply pipe stdin to the beginning of the following command to escape the contents to stdout:

cat `filename` | jq -Rs . | cut -c 2- | rev | cut -c 2- | rev

2. Assuming filename or stdin contains the following contents when viewed in an editor such as vim or nano:

    ```php
    <?php echo "Hello, world!" ?>
    ```

    :smile:

    Bobs your uncle. !@#$%^&*()_}{":?><,./;'[]-=

3. If you ran the command, the output would be:

```php\n<?php echo \"Hello, world!\" ?>\n```\n\n:smile:\n\nBobs your uncle. !@#$%^&*()_}{\":?><,./;'[]-=\n

4. In order to use it in discord.sh, all we have to do is pass that command within a subshell.

5. Usage (contents of file)

./discord.sh --webhook-url "$WEBHOOK_URL" --text "$(jq -Rs . <filename | cut -c 2- | rev | cut -c 2- | rev)"

5. Usage (contents of stdin)

./discord.sh --webhook-url "$WEBHOOK_URL" --text "$(cat filename | jq -Rs . | cut -c 2- | rev | cut -c 2- | rev)"

5. Result:

Usage (contents of stdin)

Simply pass filename to the following command to escape the file to stdout:

jq -Rs . <filename | cut -c 2- | rev | cut -c 2- | rev

Explanation

jq takes the file in as stdin then escapes it. We then pipe it to cut to remove the first 2 "indexes" meaning the first character which is a " that jq adds. We then pip that into rev to reverse the text as a whole, then pipe that into cut to remove the first 2 "indexes" or first (last) character which is once again a " that jq adds. Finally we re-reverse the text back to the standard order. The command will output to stdout

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

GPL-3.0

Made with 💖 by ChaoticWeg & fieu || Documentation and design by fieu and Matt