Discord.sh

<h4 align="center"> <br> <a href="https://github.com/fieu/discord.sh"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://i.imgur.com/hzu8Vkp.png"> <img alt="discord.sh" src="https://i.imgur.com/xZ8r3N0.png"> </picture> </a> <br> <br> </h4> <p align="center" id="badges"> <a href="https://github.com/fieu/discord.sh/actions"><img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/fieu/discord.sh/tests.yml"></a> <a href="https://github.com/fieu/discord.sh/releases/latest"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/fieu/discord.sh"></a> <a href="https://github.com/fieu/discord.sh/releases/latest"><img alt="GitHub Downloads (all assets, all releases)" src="https://img.shields.io/github/downloads/fieu/discord.sh/total"></a> <a href="https://github.com/fieu/discord.sh/stargazers"><img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/fieu/discord.sh?style=flat"></a> </p>

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

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][curl] and [jq][jq] to run 🔥

Dependencies

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

Usage

1. Setting up a Discord webhook.

1. [Setup a webhook][webhook] in the desired Discord text channel

2. Download (or clone) a copy of discord.sh

   # Using curl
   curl -o discord.sh https://github.com/fieu/discord.sh/releases/download/latest/discord.sh
   
   # Using wget
   wget -O discord.sh https://github.com/fieu/discord.sh/releases/download/latest/discord.sh
   
   # Make it executable
   chmod +x 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.

• --stdin

This allows you to pipe content from stdin instead of using --text. Any --text argument will be ignored when --stdin is used.

Example

$ echo "Hello from stdin!" | ./discord.sh --webhook-url="$WEBHOOK" --stdin

$ cat logfile.txt | ./discord.sh --webhook-url="$WEBHOOK" --stdin --username "Log Bot"

• --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][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][jq] - Character escaping
• [cut][cut] - Cut characters from string (part of [coreutils][coreutils], included by default on most systems)
• [rev][rev] - Reversing of characters (part of [util-linux][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][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 |