Signal CLI

Signal CLI enables command-line access to the Signal messenger app for sending messages, managing contacts, and automation.

Installation

Linux

# Ubuntu/Debian (using apt)
sudo apt-add-repository ppa:signal-developers/signal-ubuntu
sudo apt update
sudo apt install signal-desktop

# Or via snap
sudo snap install signal-desktop

# signal-cli (Java-based CLI)
wget https://github.com/AsamK/signal-cli/releases/download/v0.13.0/signal-cli-0.13.0-Linux.tar.gz
tar xzf signal-cli-0.13.0-Linux.tar.gz
sudo mv signal-cli /opt/signal-cli

macOS

# Homebrew
brew install signal

# signal-cli via Java
brew install signal-cli

Windows

# Scoop
scoop install signal

# Chocolatey
choco install signal

# Manual download
# https://github.com/AsamK/signal-cli/releases

Initial Setup

Register New Account

# Register phone number with Signal
signal-cli --username +PHONENUMBER register

# Verify with received SMS code
signal-cli --username +PHONENUMBER verify VERIFICATION_CODE

# Or use voice verification
signal-cli --username +PHONENUMBER verify --voice VERIFICATION_CODE

Link to Existing Account

# For secondary device (doesn't replace phone number)
signal-cli --username +PHONENUMBER link

# This returns a link URI
# Open in Signal app on main device to scan QR code

# Or set link manually
signal-cli --username +PHONENUMBER link --use-device-name "CLI Device"

Basic Messaging

Send Message

# Send SMS to contact
signal-cli --username +PHONENUMBER send --message "Hello!" +RECIPIENT_NUMBER

# Send to multiple recipients
signal-cli --username +PHONENUMBER send --message "Hi all!" +NUM1 +NUM2 +NUM3

# Send multi-line message
signal-cli --username +PHONENUMBER send --message $'Line 1\nLine 2\nLine 3' +NUMBER

# Send from file
signal-cli --username +PHONENUMBER send --message "$(cat message.txt)" +NUMBER

# Read message from stdin
echo "Message content" | \
signal-cli --username +PHONENUMBER send --message - +NUMBER

Send to Groups

# Send to group by name
signal-cli --username +PHONENUMBER send --group "Group Name" --message "Hello group!"

# Send to group by ID
signal-cli --username +PHONENUMBER send --group-id GROUPID --message "Hi!"

# List all groups
signal-cli --username +PHONENUMBER listGroups

# List group members
signal-cli --username +PHONENUMBER listGroups --show-members

Send Files

# Send image/file
signal-cli --username +PHONENUMBER send --message "See attachment:" --attachment-image photo.jpg +NUMBER

# Send multiple attachments
signal-cli --username +PHONENUMBER send --message "Files:" \
  --attachment-image photo1.jpg \
  --attachment-image photo2.jpg \
  +NUMBER

# Send document
signal-cli --username +PHONENUMBER send --message "Document:" \
  --attachment-document document.pdf +NUMBER

Contact Management

Manage Contacts

# List all contacts
signal-cli --username +PHONENUMBER listContacts

# Add contact
signal-cli --username +PHONENUMBER updateContact +PHONENUMBER --name "Contact Name"

# Update contact name
signal-cli --username +PHONENUMBER updateContact +PHONENUMBER --name "New Name"

# Show specific contact
signal-cli --username +PHONENUMBER showContact +PHONENUMBER

# List blocked contacts
signal-cli --username +PHONENUMBER listBlockedContacts

Block/Unblock

# Block contact
signal-cli --username +PHONENUMBER block +NUMBER_TO_BLOCK

# Unblock contact
signal-cli --username +PHONENUMBER unblock +BLOCKED_NUMBER

# Block group
signal-cli --username +PHONENUMBER blockGroup GROUPID

Group Management

Create Group

# Create new group
signal-cli --username +PHONENUMBER createGroup \
  --name "Group Name" \
  --member +MEMBER1 \
  --member +MEMBER2 \
  --member +MEMBER3

# Create group with description
signal-cli --username +PHONENUMBER createGroup \
  --name "Work Team" \
  --description "Team collaboration group" \
  --member +MEMBER1 \
  --member +MEMBER2

Modify Group

# Add member to group
signal-cli --username +PHONENUMBER updateGroup GROUPID \
  --add-member +NEW_MEMBER

# Remove member from group
signal-cli --username +PHONENUMBER updateGroup GROUPID \
  --remove-member +MEMBER_TO_REMOVE

# Change group name
signal-cli --username +PHONENUMBER updateGroup GROUPID \
  --name "New Group Name"

# Leave group
signal-cli --username +PHONENUMBER leaveGroup GROUPID

Message Operations

Receive Messages

# Receive messages once (and exit)
signal-cli --username +PHONENUMBER receive --timeout 1

# Receive messages with timeout (seconds)
signal-cli --username +PHONENUMBER receive --timeout 5

# Receive and print all messages
signal-cli --username +PHONENUMBER receive --timeout 10

# Daemon mode (continuous)
signal-cli --username +PHONENUMBER daemon --socket /tmp/signal.sock

View Message History

# Show conversation with contact
signal-cli --username +PHONENUMBER chatList

# Show messages from contact
signal-cli --username +PHONENUMBER showChat +CONTACT_NUMBER

# Show messages from group
signal-cli --username +PHONENUMBER showChat -g GROUPID

# Export chat history
signal-cli --username +PHONENUMBER showChat +NUMBER > chat_history.txt

Scripting Examples

Automated Notifications

#!/bin/bash
# Send automated Signal notification

SENDER="+1234567890"
RECIPIENT="+9876543210"
MESSAGE="Automated notification: $(date)"

signal-cli --username "$SENDER" send --message "$MESSAGE" "$RECIPIENT"

if [ $? -eq 0 ]; then
    echo "Message sent successfully"
else
    echo "Failed to send message"
    exit 1
fi

Monitor and Alert

#!/bin/bash
# Monitor system and send alerts via Signal

PHONE="+1234567890"
ALERT_CONTACT="+9876543210"

# Check CPU usage
CPU=$(top -bn1 | grep "Cpu(s)" | awk '{print $2}' | cut -d'%' -f1)

if (( $(echo "$CPU > 80" | bc -l) )); then
    signal-cli --username "$PHONE" send \
      --message "CPU usage high: ${CPU}%" \
      "$ALERT_CONTACT"
fi

# Check disk space
DISK=$(df -h / | tail -1 | awk '{print $5}' | cut -d'%' -f1)

if [ "$DISK" -gt 85 ]; then
    signal-cli --username "$PHONE" send \
      --message "Disk usage high: ${DISK}%" \
      "$ALERT_CONTACT"
fi

Group Announcements

#!/bin/bash
# Send announcement to multiple groups

SENDER="+1234567890"
GROUPS=("GroupID1" "GroupID2" "GroupID3")
ANNOUNCEMENT="Important announcement: $(date)"

for group in "${GROUPS[@]}"; do
    echo "Sending to group: $group"
    signal-cli --username "$SENDER" send \
      --group-id "$group" \
      --message "$ANNOUNCEMENT"
done

echo "Announcements sent"

Scheduled Messages

#!/bin/bash
# Schedule message sending with cron

# Add to crontab:
# 0 9 * * * /path/to/send_message.sh

SENDER="+1234567890"
RECIPIENT="+9876543210"
MESSAGE="Daily morning reminder"

signal-cli --username "$SENDER" send \
  --message "$MESSAGE" \
  "$RECIPIENT"

Daemon Mode

Run as Background Service

# Start daemon
signal-cli --username +PHONENUMBER daemon --socket /tmp/signal.sock &

# Send message via socket
signal-cli --username +PHONENUMBER --socket /tmp/signal.sock \
  send --message "Test" +NUMBER

# Stop daemon
pkill -f "signal-cli.*daemon"

Systemd Service

# Create service file
sudo cat > /etc/systemd/system/signal-cli.service << 'EOF'
[Unit]
Description=Signal CLI Daemon
After=network.target

[Service]
Type=simple
User=signal
ExecStart=/usr/bin/signal-cli --username +PHONENUMBER daemon --socket /tmp/signal.sock
Restart=always

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl enable signal-cli
sudo systemctl start signal-cli
sudo systemctl status signal-cli

Troubleshooting

Common Issues

Issue: “Invalid phone number format”

# Use full international format
signal-cli --username +1-123-456-7890 register  # Wrong
signal-cli --username +11234567890 register     # Correct (country code + area + number)

Issue: “Could not login: Not a valid device”

# Re-register device
signal-cli --username +PHONENUMBER unlinkDevice

# Or link to existing account
signal-cli --username +PHONENUMBER link

Issue: “Failed to send message”

# Check connection
ping -c 1 8.8.8.8

# Verify contact number format
echo "+1234567890" | signal-cli --username +PHONENUMBER validateContact

# Check if contact exists in Signal
signal-cli --username +PHONENUMBER listContacts | grep NUMBER

Issue: “Daemon connection refused”

# Ensure daemon is running
ps aux | grep signal-cli

# Restart daemon
pkill -f "signal-cli.*daemon"
sleep 2
signal-cli --username +PHONENUMBER daemon --socket /tmp/signal.sock &

Security Considerations

• Signal messages are encrypted end-to-end
• CLI tool requires phone number to register
• Keep credentials secure (no password storage)
• Use scripts with proper permissions (chmod 600)
• Never log credentials in scripts or files
• Limit access to CLI tools on shared systems
• Review script outputs for sensitive data

Integration Examples

With Alertmanager

# alertmanager config for Signal notifications
route:
  receiver: signal

receivers:
  - name: signal
    webhook_configs:
      - url: http://localhost:8080/alert

With Webhook Service

#!/bin/bash
# Receive webhook and send Signal message

while IFS= read -r alert; do
    signal-cli --username +SENDER send \
      --message "$alert" \
      +RECIPIENT
done

Related Tools

• Signal Desktop - Official desktop app
• signal-cli - Command-line client
• Automation frameworks - Script integration
• Webhooks - Event-driven messaging

---

Last updated: 2026-03-30