SMS Gateway for Android™ CLI

A command-line interface for working with SMS Gateway for Android.

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
      • Send a message
      • Get the status of a sent message
    • 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 supports the following commands:

• send - send a message with single or multiple recipients
• status - get the status of a sent message by message ID

Send a message

Syntax:

smsgate send [options] 'Message content'

Option	Description	Default value	Example
--id	Message ID, will be generated if not provided	empty	zXDYfTmTVf3iMd16zzdBj
--phone, --phones, -p	Phone number, can be used multiple times or with comma-separated values	required	+19162255887
--sim	SIM card slot number, if empty, the default SIM card will be used	empty	2
--ttl	Time-to-live (TTL), if empty, the message will not expire Conflicts with --validUntil	empty	1h30m
--validUntil	Valid until, if empty, the message will not expire Conflicts with --ttl	empty	2024-12-31T23:59:59Z

Get the status of a sent message

Syntax:

smsgate status 'Message ID'

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)