SMS Gateway for Android™ CLI

A command-line interface for interacting with the SMS Gateway for Android API
Explore the docs »

Report Bug · Request Feature

• 📱 About The Project
  • ⚙️ Built With
• 💻 Getting Started
  • Prerequisites
  • Installation
    • Option 1: Download from GitHub Releases
    • Option 2: Install using Go
    • Option 3: Docker
• 💻 Configuration
  • Available Options
  • Output Formats
• 💻 Usage
  • Commands
  • Exit codes
  • Examples
    • Output formats
• 👥 Contributing
• ©️ License
• ⚠️ Legal Notice

📱 About The Project

There are two CLI tools in this repository: smsgate and smsgate-ca. The first one is for SMS Gateway for Android itself, and the second one is for the Certificate Authority.

This CLI provides a robust interface for:

• Sending and managing SMS messages
• Configuring webhook integrations
• Issuing certificates for private deployments

⚙️ Built With

• 
• 

(back to top)

💻 Getting Started

Prerequisites

• Go 1.23+ (for building from source)
• Docker (optional, for containerized execution)

Installation

Option 1: Download from GitHub Releases

1. Go to the Releases page of this repository.
2. Download the appropriate binary for your operating system and architecture.
3. Extract the archive to a directory of your choice.
4. Move the binary to a directory in your system's PATH.

Option 2: Install using Go

go install github.com/android-sms-gateway/cli/cmd/smsgate@latest

This will download, compile, and install the latest version of the CLI tool. Make sure your Go bin directory is in your system's PATH.

Option 3: Docker

docker run -it --rm --env-file .env ghcr.io/android-sms-gateway/cli \
  send --phone '+12025550123' 'Hello, Dr. Turk!'

(back to top)

💻 Configuration

The CLI can be configured using environment variables or command-line flags. You can also use a .env file in the working directory to set these variables.

Available Options

Option	Env Var	Description	Default value
--endpoint, -e	ASG_ENDPOINT	The endpoint URL	https://api.sms-gate.app/3rdparty/v1
--username, -u	ASG_USERNAME	Your username	required
--password, -p	ASG_PASSWORD	Your password	required
--format, -f	n/a	Output format	text

Output Formats

The CLI supports three output formats:

1. text: Human-readable text output (default)
2. json: Pretty printed JSON-formatted output
3. raw: One-line JSON-formatted output

Please note that when the exit code is not 0, the error description is printed to stderr without any formatting.

(back to top)

💻 Usage

smsgate [global options] command [command options] [arguments...]

Commands

The CLI offers two main groups of commands:

• Messages: Commands for sending messages and checking their status.
• Webhooks: Commands for managing webhooks, including creating, updating, and deleting them.

For a complete list of available commands, you can:

• Run smsgate help or smsgate --help in your terminal.
• Visit the official documentation at docs.sms-gate.app.

Exit codes

The CLI uses exit codes to indicate the outcome of operations:

• 0: success
• 1: invalid options or arguments
• 2: server request error
• 3: output formatting error

Examples

For security reasons, it is recommended to pass credentials using environment variables or a .env file.

# Send a message
smsgate send --phones '+12025550123' 'Hello, Dr. Turk!'

# Send a message to multiple numbers
smsgate send --phones '+12025550123' --phones '+12025550124' 'Hello, doctors!'
# or
smsgate send --phones '+12025550123,+12025550124' 'Hello, doctors!'

# Get the status of a sent message
smsgate status zXDYfTmTVf3iMd16zzdBj

Credentials can also be passed via CLI options:

smsgate send -u <username> -p <password> --phones '+12025550123' 'Hello, Dr. Turk!'

Output formats

Text

ID: zXDYfTmTVf3iMd16zzdBj
State: Pending
IsHashed: false
IsEncrypted: false
Recipients:
        +12025550123    Pending
        +12025550124    Pending

JSON

{
  "id": "zXDYfTmTVf3iMd16zzdBj",
  "state": "Pending",
  "isHashed": false,
  "isEncrypted": false,
  "recipients": [
    {
      "phoneNumber": "+12025550123",
      "state": "Pending"
    },
    {
      "phoneNumber": "+12025550124",
      "state": "Pending"
    }
  ],
  "states": {}
}

Raw

{"id":"zXDYfTmTVf3iMd16zzdBj","state":"Pending","isHashed":false,"isEncrypted":false,"recipients":[{"phoneNumber":"+12025550123","state":"Pending"},{"phoneNumber":"+12025550124","state":"Pending"}],"states":{}}

(back to top)

👥 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

©️ License

Distributed under the Apache-2.0 license. See LICENSE for more information.

(back to top)

⚠️ Legal Notice

Android is a trademark of Google LLC.

(back to top)