Skip to content

Commit 969813f

Browse files
capcom6capcom6
committed
[integration] add new CLI options
1 parent ff286f2 commit 969813f

File tree

1 file changed

+129
-51
lines changed

1 file changed

+129
-51
lines changed

‎docs/integration/cli.md

Lines changed: 129 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -4,48 +4,72 @@ The SMS Gateway for Android™ offers its own Command Line Interface (CLI), allo
44

55
## Installation 📥
66

7-
=== ":package: Native Installation"
8-
```bash title="Linux/macOS"
9-
curl -LO https://github.com/android-sms-gateway/cli/releases/latest/download/smsgate-linux-amd64
10-
chmod +x smsgate-linux-amd64
11-
sudo mv smsgate-linux-amd64 /usr/local/bin/smsgate
7+
The CLI tool can be installed using various methods depending on your operating system and preferences. Choose the installation method that best suits your environment.
8+
9+
=== ":material-linux: Linux (x86_64)"
10+
11+
```bash
12+
curl -LO https://github.com/android-sms-gateway/cli/releases/latest/download/smsgate_Linux_x86_64.tar.gz
13+
tar -xzf smsgate_Linux_x86_64.tar.gz
14+
chmod +x smsgate
15+
sudo mv smsgate /usr/local/bin/smsgate
16+
```
17+
18+
=== ":material-apple: macOS (Apple Silicon)"
19+
20+
```bash
21+
curl -LO https://github.com/android-sms-gateway/cli/releases/latest/download/smsgate_Darwin_arm64.tar.gz
22+
tar -xzf smsgate_Darwin_arm64.tar.gz
23+
chmod +x smsgate
24+
sudo mv smsgate /usr/local/bin/smsgate
25+
```
26+
27+
=== ":material-microsoft-windows: Windows"
28+
29+
```powershell
30+
Invoke-WebRequest https://github.com/android-sms-gateway/cli/releases/latest/download/smsgate_Windows_x86_64.zip -OutFile smsgate.zip
31+
Expand-Archive smsgate.zip
1232
```
1333

1434
=== ":material-language-go: Go Install"
35+
1536
```bash
1637
go install github.com/android-sms-gateway/cli@latest
1738
```
18-
**Requirements**:
1939

40+
**Requirements**:
41+
2042
- Go 1.23+ installed
2143
- `$GOPATH/bin` in your system PATH
22-
44+
2345
!!! tip "For Developers"
24-
This method installs the latest development version.
25-
Add `export PATH=$PATH:$(go env GOPATH)/bin` to your shell config.
46+
This method installs the latest development version. Add `export PATH=$PATH:$(go env GOPATH)/bin` to your shell config.
2647

27-
=== ":window: Windows"
28-
```powershell
29-
Invoke-WebRequest https://github.com/android-sms-gateway/cli/releases/latest/download/smsgate-windows-amd64.exe -OutFile smsgate.exe
30-
Move-Item smsgate.exe "$env:ProgramFiles\SMSGATE\"
31-
```
48+
=== ":material-docker: Docker"
3249

33-
=== "🐳 Docker"
3450
```bash
3551
docker pull ghcr.io/android-sms-gateway/cli:latest
3652
```
3753

54+
For a complete list of supported platforms, please refer to the [GitHub Releases page](https://github.com/android-sms-gateway/cli/releases/latest).
55+
3856
## Configuration ⚙️
3957

40-
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.
58+
The CLI tool can be configured using command-line flags, environment variables, or a `.env` file in the working directory. This section provides detailed information about configuration options and output formats.
59+
60+
### Environment Variables
61+
62+
You can set configuration variables using a `.env` file:
4163

4264
```bash title=".env Example"
4365
ASG_ENDPOINT="https://api.sms-gate.app/3rdparty/v1"
4466
ASG_USERNAME="your_username"
4567
ASG_PASSWORD="your_password"
4668
```
4769

48-
### Options Overview
70+
### Command-line Options
71+
72+
The following table summarizes the available command-line options:
4973

5074
| Option | Env Var | Description | Default |
5175
| ------------------ | -------------- | ----------------------------------- | -------------------------------------- |
@@ -54,27 +78,26 @@ ASG_PASSWORD="your_password"
5478
| `-p`, `--password` | `ASG_PASSWORD` | :key: Auth password | **Required** |
5579
| `-f`, `--format` | - | :page_facing_up: Output format | `text` |
5680

57-
### Output formats
81+
### Output Formats
5882

59-
The CLI supports three output formats:
83+
The CLI supports three output formats for different use cases:
6084

61-
- `text` - human-readable format
85+
- `text` - human-readable format (default)
6286
- `json` - formatted JSON output
63-
- `raw` - same as `json` but without formatting
87+
- `raw` - unformatted JSON for machine consumption
6488

6589
!!! note
6690
When the exit code is not `0`, the error description is printed to stderr without any formatting.
6791

6892
## Commands 🛠️
6993

70-
The CLI offers two main groups of commands:
94+
The CLI tool provides commands for managing messages and webhooks. This section describes each command group and their available options.
7195

72-
- **Messages**: Commands for sending messages and checking their status.
73-
- **Webhooks**: Commands for managing webhooks, including creating, updating, and deleting them.
96+
### Message Commands
7497

75-
### Messages Commands
98+
Message commands allow you to send SMS messages and check their status. The following subsections detail each message-related command.
7699

77-
#### Send a Message 📨
100+
#### Send a Message
78101

79102
The `send` command allows you to send a message to one or more phone numbers.
80103

@@ -85,19 +108,31 @@ smsgate send [options] 'Message content'
85108

86109
**Options:**
87110

88-
| Option | Description | Default Value | Example |
89-
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------------- |
90-
| `--id` | A unique message ID. If not provided, one will be automatically generated. | empty | `zXDYfTmTVf3iMd16zzdBj` |
91-
| `--phone`, `--phones`, `-p` | Specifies the recipient's phone number(s). This option can be used multiple times or accepts comma-separated values. Numbers must be in E.164 format. | **required** | `+19162255887` |
92-
| `--sim`, `--simNumber` | The one-based SIM card slot number. If not specified, the device's SIM rotation feature will be used. | empty | `2` |
93-
| `--deliveryReport` | Enables delivery report for the message. | `true` | `true` |
94-
| `--priority` | Sets the priority of the message. Messages with priority >= 100 bypass all limits and delays. | `0` | `100` |
95-
| `--ttl` | Time-to-live (TTL) for the message. If not provided, the message will not expire.<br>**Conflicts with `--validUntil`.** | empty | `1h30m` |
96-
| `--validUntil` | The expiration date and time for the message. If not provided, the message will not expire.<br>**Conflicts with `--ttl`.** | empty | `2024-12-31T23:59:59Z` |
111+
| Option | Description | Default Value | Example |
112+
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------------- |
113+
| `--id` | A unique message ID. If not provided, one will be automatically generated. | empty | `zXDYfTmTVf3iMd16zzdBj` |
114+
| `--device-id` | Optional device ID for explicit selection. If not provided, a random device will be selected. | empty | `oi2i20J8xVP1ct5neqGZt` |
115+
| `--phones` | Specifies the recipient's phone number(s). This option can be used multiple times or accepts comma-separated values. Numbers must be in E.164 format. | **required** | `+12025550123` |
116+
| `--sim-number` | The one-based SIM card slot number. If not specified, the device's SIM rotation feature will be used. | empty | `2` |
117+
| `--delivery-report` | Enables delivery report for the message. | `true` | `true` |
118+
| `--priority` | Sets the priority of the message. Messages with priority >= 100 bypass all limits and delays. | `0` | `100` |
119+
| `--ttl` | Time-to-live (TTL) for the message. If not provided, the message will not expire.<br>**Conflicts with `--valid-until`.** | empty | `1h30m` |
120+
| `--valid-until` | The expiration date and time for the message. If not provided, the message will not expire.<br>**Conflicts with `--ttl`.** | empty | `2024-12-31T23:59:59Z` |
121+
| `--data` | Send data message instead of text (content in base64). | `false` | `true` |
122+
| `--data-port` | Destination port for data message (1 to 65535). | `53739` | `12345` |
123+
| `--skip-phone-validation` | Skip phone number validation. | `false` | `true` |
124+
| `--device-active-within` | Time window in hours for device activity filtering. `0` means no filtering. | `0` | `12` |
125+
126+
!!! note "Disabling booleans"
127+
To disable, use `--delivery-report=false`.
128+
129+
!!! tip
130+
For sending data messages, ensure the content is properly base64 encoded.
131+
Example: `echo -n 'hello world' | base64` → `aGVsbG8gd29ybGQ=`
97132

98133
---
99134

100-
#### Get the Status of a Message ⏱️
135+
#### Get Message Status
101136

102137
The `status` command retrieves the status of a message using its ID.
103138

@@ -106,11 +141,16 @@ The `status` command retrieves the status of a message using its ID.
106141
smsgate status 'Message ID'
107142
```
108143

144+
!!! note
145+
The status command requires the message ID returned from the `send` command.
146+
109147
---
110148

111-
### Webhooks Commands 🌐
149+
### Webhook Commands
112150

113-
#### Register a Webhook 📝
151+
Webhook commands allow you to manage webhooks for event notifications. The following subsections detail each webhook-related command.
152+
153+
#### Register Webhook
114154

115155
The `register` command allows you to register a new webhook.
116156

@@ -126,9 +166,12 @@ smsgate webhooks register [options] URL
126166
| `--id` | A unique webhook ID. If not provided, one will be automatically generated. | empty | `zXDYfTmTVf3iMd16zzdBj` |
127167
| `--event`, `-e` | The event name for which the webhook will be triggered. | **required** | `sms:received` |
128168

169+
!!! important
170+
Ensure your webhook endpoint is accessible from the device and properly secured.
171+
129172
---
130173

131-
#### List Webhooks 📜
174+
#### List Webhooks
132175

133176
The `list` command displays all registered webhooks.
134177

@@ -137,9 +180,12 @@ The `list` command displays all registered webhooks.
137180
smsgate webhooks list
138181
```
139182

183+
!!! tip
184+
Use this command to audit your webhook configurations regularly.
185+
140186
---
141187

142-
#### Delete a Webhook 🗑️
188+
#### Delete Webhook
143189

144190
The `delete` command removes a webhook by its ID.
145191

@@ -148,22 +194,41 @@ The `delete` command removes a webhook by its ID.
148194
smsgate webhooks delete 'Webhook ID'
149195
```
150196

151-
## Usage examples 💡
197+
!!! warning
198+
Deleting a webhook is irreversible. Ensure you no longer need the webhook before deleting it.
152199

153-
For security reasons, it is recommended to pass credentials using environment variables or a `.env` file.
200+
## Usage Examples 💡
201+
202+
This section provides practical examples of using the CLI tool for various tasks. For security reasons, it is recommended to pass credentials using environment variables or a `.env` file.
203+
204+
### Basic Operations
154205

155206
```bash
156207
# Send a message
157-
smsgate send --phone '+19162255887' 'Hello, Dr. Turk!'
208+
smsgate send --phones '+12025550100' 'Hello, Dr. Turk!'
158209

159210
# Send a message to multiple numbers
160-
smsgate send --phone '+19162255887' --phone '+19162255888' 'Hello, doctors!'
211+
smsgate send --phones '+12025550100' --phones '+12025550101' 'Hello, doctors!'
161212
# or
162-
smsgate send --phones '+19162255887,+19162255888' 'Hello, doctors!'
213+
smsgate send --phones '+12025550100,+12025550101' 'Hello, doctors!'
214+
215+
# Send a message with a specific device
216+
smsgate send --device-id 'DwWLuSmLbXvwzF8mbmTE8' --phones '+12025550100' 'Hello from specific device!'
217+
218+
# Send a data message
219+
smsgate send --data --data-port 12345 --phones '+12025550100' 'aGVsbG8gd29ybGQ='
220+
```
163221

222+
### Message Management
223+
224+
```bash
164225
# Get the status of a sent message
165226
smsgate status zXDYfTmTVf3iMd16zzdBj
227+
```
166228

229+
### Webhook Management
230+
231+
```bash
167232
# Register a webhook for received messages
168233
smsgate webhooks register --event 'sms:received' 'https://example.com/webhook'
169234

@@ -174,24 +239,31 @@ smsgate webhooks list
174239
smsgate webhooks delete 'webhook-id'
175240
```
176241

242+
### Alternative Credential Methods
243+
177244
Credentials can also be passed via CLI options:
178245

179246
```bash
180247
# Pass credentials by options
181248
smsgate send -u <username> -p <password> \
182-
--phone '+19162255887' 'Hello, Dr. Turk!'
249+
--phones '+12025550100' 'Hello, Dr. Turk!'
183250
```
184251

252+
### Using Docker
253+
185254
If you prefer not to install the CLI tool locally, you can use Docker to run it:
186255

187256
```bash
188257
docker run -it --rm --env-file .env ghcr.io/android-sms-gateway/cli \
189-
send --phone '+19162255887' 'Hello, Dr. Turk!'
258+
send --phones '+12025550100' 'Hello, Dr. Turk!'
190259
```
191260

192-
## Exit codes 🔚
261+
!!! tip
262+
Using Docker is ideal for CI/CD pipelines or environments where you want to avoid local installations.
263+
264+
## Exit Codes 🔚
193265

194-
The CLI uses exit codes to indicate the outcome of operations:
266+
The CLI tool uses exit codes to indicate the outcome of operations. Properly handling these codes in scripts can improve error handling and automation.
195267

196268
| Code | Description |
197269
| ---- | --------------------- |
@@ -200,6 +272,12 @@ The CLI uses exit codes to indicate the outcome of operations:
200272
| 2 | 🌐 Network error |
201273
| 3 | 📄 Output format error |
202274

203-
---
275+
!!! failure
276+
Exit codes other than 0 indicate errors. Always check the error message output for troubleshooting information.
277+
278+
## See Also 📚
279+
280+
For more information about integrating the SMS Gateway, explore the following resources:
204281

205-
[:material-github: CLI Repository](https://github.com/android-sms-gateway/cli)
282+
- [:material-github: CLI Repository](https://github.com/android-sms-gateway/cli)
283+
- [:material-api: API Reference](./api.md)

0 commit comments

Comments
 (0)