⚡ Quick Start Guide

Get ChatrixCD up and running in 2 minutes! 🚀

⏱️ Time to Success: ~2 minutes
📋 What You'll Need: Matrix account, Semaphore UI access
🎯 What You'll Get: Fully working CI/CD bot in your chat!

Step 1️⃣: Download & Run

📦 Download from the Download Page

✅ No Python required! Pre-built binaries for Linux.

Visit the Download Page to get the latest binary for your platform.

# Example for x86_64:
wget https://github.com/CJFWeatherhead/ChatrixCD/releases/latest/download/chatrixcd-linux-x86_64.dist.tar.gz
tar -xzf chatrixcd-linux-x86_64.dist.tar.gz
cd chatrixcd-linux-x86_64.dist
./chatrixcd

✅ Success! The bot will guide you through configuration if config.json doesn't exist. Keep this terminal open.

Step 2️⃣: Invite Bot to Your Room

In your Matrix client (Element, etc.):

1️⃣

Create or open a Matrix room
Can be encrypted or unencrypted

2️⃣

Invite your bot
Use the user_id from your config: @your-bot:matrix.org

3️⃣

Bot auto-accepts the invite
Look for a friendly greeting! 👋

Step 3️⃣: Start Using Commands!

Try these commands in your Matrix room:

!cd help

📖 See all available commands

!cd projects

📋 List Semaphore projects

!cd templates 1

📄 List templates for project 1

!cd run 1 2

🚀 Run template 2 in project 1

!cd status

📊 Check last task status

!cd logs

📝 View logs for last task

🧩 Advanced Run Options

You can pass tags and raw arguments when running a template:

Positional tags: !cd run 4 5 update,molecule
Flagged tags: !cd run 4 5 --tags=update,molecule
Raw args: !cd run 3 1 --args="--some --args -e"

Notes:

If the target template does not support tags/arguments, the bot will warn you and suggest running without them.
Quoted arguments are supported.

🔖 Command Aliases

Speed up common actions by creating your own shortcuts:

Add: !cd aliases add <alias> <command>
- Works with prefixed or unprefixed commands
- Example: !cd aliases add deploy run 4 5 --tags=prod --arg="--dry-run"
Remove: !cd aliases remove <alias>
List: !cd aliases

Aliases expand with any extra arguments you append when using them. For example, if deploy maps to run 4 5, then typing !cd deploy --tags=prod runs !cd run 4 5 --tags=prod.

Note: The base command must be a valid bot command; extra flags are passed through unchanged.

🎯 Example Workflow

Here’s a complete example of running a deployment:

You: !cd projects
Bot: 📋 Projects:
     1. Production Website
     2. API Server

You: !cd templates 1
Bot: 📄 Templates for "Production Website":
     1. Deploy to Staging
     2. Deploy to Production

You: !cd run 1 2
Bot: 🚀 Ready to run "Deploy to Production"?
     React with 👍 to confirm or 👎 to cancel

You: [React with 👍]
Bot: ✅ Task started! Task ID: 42
     I'll keep you posted! 📊

[After a few minutes]
Bot: ✅ Task #42 completed successfully! 🎉
     Duration: 3m 24s