signal-account-cli

An unofficial, multi-account terminal interface for signal-cli. It uses Clack for interactive prompts, a Python backend for local message history, and one private systemd user service per linked account.

Requirements

• Linux with systemd user services
• Node.js 20.12 or newer
• Python 3.11 or newer
• signal-cli 0.14.6 or newer and its required Java runtime

Install

npm install --global signal-account-cli
signal setup

signal setup installs the user-service template. It does not start a service, link an account, or modify existing account data. After package upgrades, use:

signal setup --restart

The default account profiles are personal and agent. Override them before setup with a comma-separated list:

export SIGNAL_ACCOUNTS=personal,work
signal setup

Use

Run signal without arguments for the interactive account and command menus.

signal link --account agent
signal chats --account agent --page-number 1
signal messages --account agent --chat-id 'CHAT_ID' --page-number 2
signal send --account agent --chat-id 'CHAT_ID' --message 'Hello'
signal status --account agent --json

An account profile can also expose an opt-in, loopback-only, signal-cli-compatible HTTP/SSE bridge. This lets local agent software such as Hermes use the same managed receiver without starting a second signal-cli process. The private Unix socket used by the signal command remains active.

Chat pages contain 10 conversations. Message pages contain 50 messages by default. Both put the newest result first.

A contact ID returned by signal contacts is also a direct chat ID. To start a chat with a number that is not in contacts, use its full E.164 form:

signal send --account agent --chat-id '+15557654321' --message 'Hello'

See docs/usage.md for every command and operational detail.

Account data

The package stores private state outside the npm installation:

~/.local/share/signal/ACCOUNT/

Reinstalling or upgrading the npm package does not replace that directory. Never copy account data, databases, attachments, or backups into this repository.

Uninstall

Stop and disable each account service before removing the package:

systemctl --user disable --now [email protected]
systemctl --user disable --now [email protected]
npm uninstall --global signal-account-cli

Uninstalling leaves account data in ~/.local/share/signal/ so an accidental package removal does not destroy linked-device keys or message history.

License

MIT. This project is not affiliated with or endorsed by Signal Messenger LLC.