smsgate-cli

name	smsgate-cli
description	Use when you need to send SMS messages, manage webhooks, check delivery status, retrieve logs, or issue CA certificates via the SMS Gateway for Android API. Triggered on SMS sending, webhook management, message status checks, and log retrieval.
license	Apache-2.0

SMSGate CLI

A CLI tool for interacting with the SMS Gateway for Android API. Ships two binaries:

• smsgate — send SMS, batch operations, manage webhooks, fetch logs
• smsgate-ca — issue TLS certificates for private deployments

Installation

Option 1: GitHub Releases

Download the latest archive from the Releases page. Archives are built with GoReleaser for Linux, macOS, and Windows. Each archive contains both smsgate and smsgate-ca.

Archive naming: smsgate_Linux_x86_64.tar.gz, smsgate_Windows_x86_64.zip, smsgate_Darwin_arm64.tar.gz, etc.

# Use bash: extract archive and move binaries into PATH
tar xzf smsgate_Linux_x86_64.tar.gz
sudo mv smsgate smsgate-ca /usr/local/bin/

Option 2: Install using Go

# Use bash: install via Go toolchain
go install github.com/android-sms-gateway/cli/cmd/smsgate@latest
go install github.com/android-sms-gateway/cli/cmd/smsgate-ca@latest

Note: Replace @latest with a specific version tag (e.g. @v1.2.3) for reproducible installs.

Option 3: Docker

# Use bash: run via Docker
docker run -it --rm --env-file .env ghcr.io/android-sms-gateway/cli \
  send --phones '[phone]' 'Hello!'

The Docker image includes both smsgate (entrypoint) and smsgate-ca.

Updating

• Go: Re-run the go install commands above with the target version tag.
• Docker: docker pull ghcr.io/android-sms-gateway/cli

Configuration

Credentials can be passed via CLI flags, environment variables, or a .env file.

Flag	Env Var	Description	Default
--endpoint, -e	ASG_ENDPOINT	API endpoint URL	https://api.sms-gate.app/3rdparty/v1
--username, -u	ASG_USERNAME	Username	required
--password, -p	ASG_PASSWORD	Password	required
--format, -f	—	Output format	text

The .env file in the working directory is loaded automatically.

Commands

smsgate send

Send a text or data (binary) SMS message.

smsgate send [flags] <message>

Flag	Description	Default
--phones, -p	Recipient phone number(s), E.164 format (repeatable or comma-separated)	required
--id	Custom message ID	auto-generated
--device-id, --device	Specific device ID	auto
--sim-number, --sim	SIM slot (one-based)	device default
--delivery-report	Enable delivery report	true
--priority	Priority (-128 to 127; >= 100 bypasses limits)	0
--ttl	Time-to-live (e.g. 1h30m)	unlimited
--valid-until	Expiration time (RFC3339)	unlimited
--schedule-at	Schedule delivery time (RFC3339)	immediate
--skip-phone-validation	Skip phone validation	false
--device-active-within	Filter by device activity (hours)	0 (no filter)
--data	Send data message (content must be base64)	false
--data-port	Destination port for data message	53739

smsgate status

Check the delivery state of a sent message.

smsgate status <message-id>

smsgate batch send

Send messages in bulk from a CSV or XLSX file.

smsgate batch send [flags] <filename>

Flag	Description	Default
--map	Column mapping: phone=Col,text=Col (comma-separated)	required
--sheet	Sheet name (XLSX only)	first sheet
--delimiter	CSV delimiter	,
--header	Treat first row as header	true
--dry-run	Validate and preview without sending	false
--validate-only	Validate input only (no preview)	false
--concurrency	Number of concurrent workers	CPU cores
--continue-on-error	Continue after per-row failures	false

Also accepts the shared flags from send (--device-id, --sim-number, --priority, --ttl, --valid-until, --delivery-report, --skip-phone-validation, --device-active-within), applied to every message in the batch.

Column mapping fields:

Field	Required	Description
phone	yes	Phone number
text	yes	Message text
id	no	Custom message ID
device_id	no	Device identifier
sim_number	no	SIM slot number
priority	no	Message priority

Workflow modes:

1. Validate only — check file and mapping: --validate-only
2. Dry run — preview all parsed rows: --dry-run
3. Full send — send with progress: --concurrency=5

smsgate webhooks

Manage webhooks for event notifications.

# Register a webhook
smsgate webhooks register --event <event> [--id ID] [--device-id DEVICE] <url>

# List all webhooks
smsgate webhooks list

# Delete a webhook
smsgate webhooks delete <id>

Events: sms:received, sms:sent, sms:failed, device:connected, device:disconnected

smsgate logs

Retrieve logs within a time range.

smsgate logs [--from TIME] [--to TIME]

Dates use RFC3339 format (e.g. 2024-01-15T10:30:00Z). Defaults to the last 24 hours.

smsgate-ca

Issue TLS certificates for private SMS Gateway deployments.

smsgate-ca [--timeout DURATION] webhooks [--out FILE] [--keyout FILE] <ip-address>
smsgate-ca [--timeout DURATION] private [--out FILE] [--keyout FILE] <ip-address>

Flag	Description	Default
--timeout, -t	Request timeout	30s
--out	Certificate output file	server.crt
--keyout	Private key output file	server.key

The IP address must be a private (RFC 1918) address.

Output Formats

All commands support --format (or -f) with four options:

• text — human-readable key:value pairs (default)
• json — pretty-printed JSON
• raw — compact one-line JSON
• table — tab-aligned columns

Error messages are always printed to stderr in plain text regardless of format.

Exit Codes

Code	Meaning
0	Success
1	Invalid options or arguments
2	Server request error
3	Output formatting error
4	Internal error

Examples

# Send a text message
smsgate send --phones '[phone]' 'Hello, Dr. Turk!'

# Send to multiple phones
smsgate send --phones '[phone],[phone]' 'Hello!'

# Send with priority (bypasses limits)
smsgate send --phones '[phone]' --priority 100 'Urgent'

# Send a data message
echo -n 'hello' | base64
smsgate send --phones '[phone]' --data --data-port 12345 'aGVsbG8='

# Check message status
smsgate status zXDYfTmTVf3iMd16zzdBj

# Batch send from CSV
smsgate batch send contacts.csv --map phone=Phone,text=Message

# Batch send from XLSX with a specific sheet
smsgate batch send campaign.xlsx --sheet Sheet1 --map phone=Phone,text=Message

# Dry-run batch (validate + preview)
smsgate batch send contacts.csv --map phone=Phone,text=Message --dry-run

# Register a webhook
smsgate webhooks register --event sms:received https://example.com/hook

# List webhooks (table format)
smsgate --format table webhooks list

# Delete a webhook
smsgate webhooks delete wh_abc123

# Get logs for a specific time range
smsgate logs --from '2024-01-15T00:00:00Z' --to '2024-01-15T23:59:59Z'

# Issue a CA certificate for webhooks
smsgate-ca webhooks 192.168.1.100 --out server.crt --keyout server.key

# Issue a CA certificate for a private server
smsgate-ca private 10.0.0.5 --out myserver.crt --keyout myserver.key