signal-cli-py 0.4.0

Reusable Python library and CLI for sending text and images via signal-cli-rest-api. Supports both individuals (phone numbers) and groups.

signal-cli

A reusable Python library and CLI for sending text messages and images via signal-cli-rest-api.

It supports sending to both Signal groups and individual phone numbers, and can discover groups your linked account is a member of.

Installation

pip install signal-cli-py

For CLI usage via isolated environment (recommended):

pipx install signal-cli-py

Note: After installing, the command is still signal-cli (not signal-cli-py).
Example: signal-cli send --recipient team "Hello"

This is intentional — the PyPI package name is signal-cli-py to avoid a naming conflict with an older package.

Quick Start

As a Library

from signal_cli import SignalClient, SignalConfig

# Load from default config (~/.signal-cli/config.json)
client = SignalClient()

# Send to a saved recipient (group or phone number)
client.send("Hello from Python", recipient="team-updates")

# Send with an image
client.send(
    "Weekly report",
    recipient="[phone]",
    attachments=[{"filename": "report.png", "data": base64_data}]
)

# Discover live groups from your linked account
groups = client.list_remote_groups()
for g in groups:
    print(g["name"], g["id"])

As a CLI

# Basic setup (stores number + API URL)
signal-cli setup

# List groups your linked account can see
signal-cli group-list --available

# Send a message
signal-cli send --recipient team-updates "Hello team"

# Send with image
signal-cli send --recipient team-updates --image ./chart.png "Weekly update"

Configuration

By default, configuration is stored at ~/.signal-cli/config.json.

You can override the config location in two ways:

# Explicit path
cfg = SignalConfig(config_path="/path/to/my-signal.json")
client = SignalClient(config=cfg)

# Via environment variable
export SIGNAL_CLI_CONFIG=/path/to/my-signal.json

Important: Linked Device Behavior

This tool is designed to be used as a linked device (not a primary registration).

• New groups created on your phone may not immediately appear when calling list_remote_groups() or group-list --available.
• Common triggers that make new groups visible:
  • Send/receive a message inside the group from your phone
  • Restart the signal-cli-rest-api container
  • Re-link the device (most reliable)

If a group is missing, the recommended first step is to send a message in it from your phone and then re-check.

Docker Requirement

Sending requires a running signal-cli-rest-api container (usually managed via Docker Compose).

The recommended compose file is automatically installed to ~/.signal-cli/docker-compose.yml when you run signal-cli setup (or you can manage it yourself).

This package defaults to MODE=native in the generated compose file. native mode provides good performance while avoiding certain linking and compatibility issues that can occur with json-rpc mode (the upstream default in some contexts).

Development

cd signal-cli
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

License

MIT