/cli

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

Primary LanguageGoApache License 2.0Apache-2.0

SMS Gateway for Android™ CLI

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

Table of Contents

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, E.164 format required +19162255887
--sim, --simNumber One-based 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 support@sms-gate.app

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