SMS Gateway for Android™ CLI

A command-line interface for interacting with the SMS Gateway for Android API.

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.

Table of Contents

• SMS Gateway for Android™ CLI
  • Table of Contents
  • Installation
    • Option 1: Download from GitHub Releases
    • Option 2: Install using Go
  • Configuration
    • Available Options
    • Output Formats
  • Usage
    • Commands
    • Exit codes
    • Examples
      • Output formats
  • Support
  • Contributing
  • License
  • Legal Notice

Installation

You can install the SMS Gateway CLI in two ways:

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. Rename the downloaded file to smsgate (or smsgate.exe for Windows).
4. Move the binary to a directory in your system's PATH.

For example, on Linux or macOS:

mv /path/to/downloaded/binary /usr/local/bin/smsgate
chmod +x /usr/local/bin/smsgate

Option 2: Install using Go

If you have Go installed on your system (version 1.23 or later), you can use the go install command:

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.

After installation, you can run the CLI tool using the smsgate command.

(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 --phone '+19162255887' 'Hello, Dr. Turk!'

# Send a message to multiple numbers
smsgate send --phone '+19162255887' --phone '+19162255888' 'Hello, doctors!'
# or
smsgate send --phones '+19162255887,+19162255888' 'Hello, doctors!'

# Get the status of a sent message
smsgate status zXDYfTmTVf3iMd16zzdBj

Credentials can also be passed via CLI options:

# Pass credentials by options
smsgate send -u <username> -p <password> --phone '+19162255887' 'Hello, Dr. Turk!'

If you prefer not to install the CLI tool locally, you can use Docker to run it:

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

Output formats

Text

ID: zXDYfTmTVf3iMd16zzdBj
State: Pending
IsHashed: false
IsEncrypted: false
Recipients: 
        +19162255887    Pending
        +19162255888    Pending

JSON

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

Raw

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

(back to top)

Support

For support, please contact [email protected]

(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)