Send Slack

A powerful CLI tool to send formatted Markdown messages to Slack using webhooks or API tokens.

Features

• Convert Markdown to Slack blocks
• Support for complex Markdown elements (headings, lists, code blocks, etc.)
• Automatic splitting of long messages to comply with Slack's limits
• Option to send pre-formatted Slack blocks
• Add title, context, and start text to your messages
• Read input from files or directly from the command line
• Support for both webhook URLs and API tokens

Installation

npm install -g send-slack

Usage

You can use this package with npx without installing it globally:

npx send-slack [options]

Or if you've installed it globally:

send-slack [options]

Options

| Option | Alias | Description | Type | Required | |--------|-------|-------------|------|----------| | --webhook | -w | Slack webhook URL | string | No* | | --token | -T | Slack API token (Bot User OAuth Token) | string | No* | | --channel | -C | Slack channel ID or name (required when using token) | string | No** | | --markdown | -m | Markdown string or file path | string | No*** | | --blocks | -b | JSON string of Slack blocks or file path | string | No*** | | --title | -t | Heading for the message | string | No | | --context | -c | Context array as a JSON string | string | No | | --start-text | -s | Start text for the message | string | No | | --help | -h | Show help | boolean | No |

*Either --webhook or --token must be provided
**Required when using --token
***Either --markdown or --blocks must be provided

Authentication Methods

Webhook URL (Simple)

Use a webhook URL for simple integration. This is the easiest method but requires setting up an incoming webhook in your Slack workspace.

1. Go to your Slack workspace settings
2. Navigate to "Apps" → "Manage" → "Custom Integrations" → "Incoming Webhooks"
3. Create a new webhook and copy the URL

API Token (Advanced)

Use a Bot User OAuth Token for more advanced features and better control. This method requires:

1. Create a Slack App:

   • Go to https://api.slack.com/apps
   • Click "Create New App" → "From scratch"
   • Give your app a name and select your workspace

2. Configure Bot Permissions:

   • Go to "OAuth & Permissions" in your app settings
   • Under "Scopes" → "Bot Token Scopes", add:
     • chat:write (to send messages)
     • chat:write.public (to send messages to public channels)

3. Install App to Workspace:

   • Click "Install to Workspace"
   • Copy the "Bot User OAuth Token" (starts with xoxb-)

4. Use the token:

   • The channel can be:
     • Channel ID (e.g., C1234567890)
     • Channel name with # (e.g., #general)
     • Direct message with @ (e.g., @username)
     • Direct message with user ID (e.g., U1234567890)

Examples

Send a Markdown message using webhook

npx send-slack --webhook "https://hooks.slack.com/services/XXX/YYY/ZZZ" --markdown "# Hello World\n\nThis is a test message."

Send a Markdown message using API token

npx send-slack --token "xoxb-your-bot-token" --channel "#general" --markdown "# Hello World\n\nThis is a test message."

Send a message from a Markdown file

# Using webhook
npx send-slack --webhook "https://hooks.slack.com/services/XXX/YYY/ZZZ" --markdown ./message.md

# Using API token
npx send-slack --token "xoxb-your-bot-token" --channel "C1234567890" --markdown ./message.md

Send pre-formatted Slack blocks

# Using webhook
npx send-slack --webhook "https://hooks.slack.com/services/XXX/YYY/ZZZ" --blocks '[{"type":"section","text":{"type":"mrkdwn","text":"Hello, World!"}}]'

# Using API token
npx send-slack --token "xoxb-your-bot-token" --channel "#general" --blocks '[{"type":"section","text":{"type":"mrkdwn","text":"Hello, World!"}}]'

Send a message with a title and context

npx send-slack --webhook "https://hooks.slack.com/services/XXX/YYY/ZZZ" --markdown "This is the main message." --title "Important Announcement" --context '["Posted by: John Doe", "Date: 2023-06-01"]'

Markdown Support

This tool supports a wide range of Markdown elements, including:

• Headings (H1 to H6)
• Bold and italic text
• Strikethrough
• Unordered and ordered lists
• Code blocks (with language highlighting)
• Blockquotes
• Horizontal rules
• Links
• Images

Slack Message Limits

This tool automatically handles Slack's message limits:

• Maximum of 50 blocks per message
• Maximum text length of 3000 characters per block
• Maximum total message length of 40,000 characters

Long messages are automatically split into multiple Slack messages while preserving formatting.

Error Handling

If an error occurs during execution, the tool will output an error message to the console and exit with a non-zero status code.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.