# slackecho

Need a quick way to send a message to Slack from the command line? This will do the job (and not much else).

Useful inside scripts to report back to an administrator, monitor cron jobs, or integrate with CI/CD pipelines.

## What is this repository for?

- **Single-purpose shell script** that uses `curl` to send messages to Slack via incoming webhooks
- **Minimal scope**: Message delivery only, no complex features or dependencies beyond `curl`
- **Lightweight**: Designed for integration into bash scripts, cron jobs, and automation pipelines
- Maintained by [Hansen IT Solutions](https://hansenit.solutions)

## Installation

1. **Install curl** (if not already present)
   ```bash
   # Ubuntu/Debian
   sudo apt-get install curl
   
   # macOS
   brew install curl
   
   # CentOS/RHEL
   sudo yum install curl
   ```

2. **Copy script to binary path**
   ```bash
   sudo cp slackecho /usr/local/bin/
   sudo chmod +x /usr/local/bin/slackecho
   ```

3. **Configure Slack webhook URL**
   - Update the `SLACKURL` variable in the script with your Slack incoming webhook URL
   - Create a Slack webhook: https://api.slack.com/messaging/webhooks

## Usage

### Command Signature

```bash
slackecho <message> [username] [channel] [icon]
```

### Parameters

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `message` | Yes | N/A | Text to send to Slack |
| `username` | No | `slackecho-user` | Display name of the Slack message sender |
| `channel` | No | `general` | Target Slack channel (without # prefix) |
| `icon` | No | `:robot_face:` | Slack emoji icon for the message |

### Examples

Send a simple message to the default channel:
```bash
slackecho "Backup complete"
```

Send a message with a custom username:
```bash
slackecho "Build failed" "CI-Bot"
```

Send to a specific channel:
```bash
slackecho "Deployment complete" "deploy-bot" "deployments"
```

Use a custom icon:
```bash
slackecho "Alert!" "monitoring" "alerts" ":warning:"
```

## Integration Examples

### Cron Job
```bash
# Report cron job status to Slack
0 2 * * * /path/to/backup.sh && slackecho "Daily backup succeeded" || slackecho "Daily backup failed"
```

### Bash Script
```bash
#!/bin/bash
if command -v someapp &> /dev/null; then
    slackecho "someapp is installed" "admin"
else
    slackecho "someapp is NOT installed" "admin" "alerts" ":warning:"
fi
```

### CI/CD Pipeline
```bash
# In your CI/CD script
slackecho "Build #${CI_JOB_ID} completed" "CI" "builds"
```

## Configuration

Currently, the webhook URL and default values are hardcoded in the script. Future versions will support:
- External configuration file
- Environment variables for SLACKURL
- Customizable default values per installation

To customize now, edit these variables in the `slackecho` script:
- `SLACKURL`: Your Slack incoming webhook URL
- `SLACKUSER`: Default username (default: "slackecho-user")
- `SLACKCH`: Default channel (default: "general")
- `SLACKICON`: Default emoji icon (default: ":robot_face:")

## Dependencies

- **curl**: For HTTP POST requests to Slack
- **bash**: Shell script runtime

## Architecture

The script follows a simple flow:
1. Validate that at least one argument (message) is provided
2. Set default values for optional parameters
3. Build a JSON payload with channel, username, text, and icon_emoji fields
4. POST the payload to the Slack webhook URL using `curl`
5. Suppress output and errors

## Testing

Currently no automated tests are in place. Contributions for a lightweight bash test framework (e.g., BATS) are welcome.

To manually test:
```bash
./slackecho "Test message" "TestBot" "general"
```

## Error Handling

Currently, the script silently ignores POST failures. Output is suppressed to `/dev/null`. For debugging:
1. Comment out the `>/dev/null 2>&1` at the end of the curl command
2. Verify your SLACKURL is correct
3. Ensure the webhook still exists in your Slack workspace

## Contribution Guidelines

Contributions are welcome! Please:
1. Keep changes minimal and focused on core functionality
2. Maintain bash compatibility
3. Test changes before submitting
4. Follow the existing code style (parameter handling, error suppression)

See [TODO](#todo) for planned improvements.

## TODO

- [ ] Create external configuration file
- [ ] Support environment variables for SLACKURL
- [ ] Add bash syntax checking to CI/CD pipeline
- [ ] Create BATS-based test framework
- [ ] Implement optional logging
- [ ] Formalize code review process

## Contact

- **Maintainer**: gary@hansenit.solutions
- **Organization**: [Hansen IT Solutions](https://hansenit.solutions)