Metadata-Version: 2.4
Name: signal-cli-py
Version: 0.3.0
Summary: Reusable Python library and CLI for sending text and images via signal-cli-rest-api. Supports both individuals (phone numbers) and groups.
Project-URL: Homepage, https://github.com/jower999/signal-cli
Project-URL: Repository, https://github.com/jower999/signal-cli
Project-URL: Issues, https://github.com/jower999/signal-cli/issues
Author: signal-cli maintainers
License-Expression: MIT
License-File: LICENSE
Keywords: delivery,notifications,signal,signal-cli,signal-messaging
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: requests>=2.32.0
Requires-Dist: typer[all]>=0.12.0
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: responses>=0.25.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# signal-cli

A reusable Python library and CLI for sending text messages and images via [signal-cli-rest-api](https://github.com/bbernhard/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

```bash
pip install signal-cli-py
```

For CLI usage via isolated environment (recommended):

```bash
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

```python
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="+46700000001",
    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

```bash
# 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:

```python
# 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 installed to `~/.signal-cli/docker-compose.yml` (or you can manage it yourself).

## Development

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

## License

MIT