Skip to content

Commit e02bee4

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

File tree

1 file changed

+122
-46
lines changed

1 file changed

+122
-46
lines changed

‎docs/integration/cli.md

Lines changed: 122 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -4,48 +4,70 @@ 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+
=== ":penguin: 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+
=== ":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
1225
```
1326

1427
=== ":material-language-go: Go Install"
28+
1529
```bash
1630
go install github.com/android-sms-gateway/cli@latest
1731
```
18-
**Requirements**:
1932

33+
**Requirements**:
34+
2035
- Go 1.23+ installed
2136
- `$GOPATH/bin` in your system PATH
22-
37+
2338
!!! tip "For Developers"
24-
This method installs the latest development version.
25-
Add `export PATH=$PATH:$(go env GOPATH)/bin` to your shell config.
39+
This method installs the latest development version. Add `export PATH=$PATH:$(go env GOPATH)/bin` to your shell config.
2640

2741
=== ":window: Windows"
42+
2843
```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\"
44+
Invoke-WebRequest https://github.com/android-sms-gateway/cli/releases/latest/download/smsgate_Windows_x86_64.zip -OutFile smsgate.zip
45+
Expand-Archive smsgate.zip
3146
```
3247

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

3854
## Configuration ⚙️
3955

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.
56+
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.
57+
58+
### Environment Variables
59+
60+
You can set configuration variables using a `.env` file:
4161

4262
```bash title=".env Example"
4363
ASG_ENDPOINT="https://api.sms-gate.app/3rdparty/v1"
4464
ASG_USERNAME="your_username"
4565
ASG_PASSWORD="your_password"
4666
```
4767

48-
### Options Overview
68+
### Command-line Options
69+
70+
The following table summarizes the available command-line options:
4971

5072
| Option | Env Var | Description | Default |
5173
| ------------------ | -------------- | ----------------------------------- | -------------------------------------- |
@@ -54,27 +76,26 @@ ASG_PASSWORD="your_password"
5476
| `-p`, `--password` | `ASG_PASSWORD` | :key: Auth password | **Required** |
5577
| `-f`, `--format` | - | :page_facing_up: Output format | `text` |
5678

57-
### Output formats
79+
### Output Formats
5880

59-
The CLI supports three output formats:
81+
The CLI supports three output formats for different use cases:
6082

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

6587
!!! note
6688
When the exit code is not `0`, the error description is printed to stderr without any formatting.
6789

6890
## Commands 🛠️
6991

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

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

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

77-
#### Send a Message 📨
98+
#### Send a Message
7899

79100
The `send` command allows you to send a message to one or more phone numbers.
80101

@@ -85,19 +106,31 @@ smsgate send [options] 'Message content'
85106

86107
**Options:**
87108

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` |
109+
| Option | Description | Default Value | Example |
110+
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------------- |
111+
| `--id` | A unique message ID. If not provided, one will be automatically generated. | empty | `zXDYfTmTVf3iMd16zzdBj` |
112+
| `--device-id` | Optional device ID for explicit selection. If not provided, a random device will be selected. | empty | `oi2i20J8xVP1ct5neqGZt` |
113+
| `--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** | `+19162255887` |
114+
| `--sim-number` | The one-based SIM card slot number. If not specified, the device's SIM rotation feature will be used. | empty | `2` |
115+
| `--delivery-report` | Enables delivery report for the message. | `true` | `true` |
116+
| `--priority` | Sets the priority of the message. Messages with priority >= 100 bypass all limits and delays. | `0` | `100` |
117+
| `--ttl` | Time-to-live (TTL) for the message. If not provided, the message will not expire.<br>**Conflicts with `--valid-until`.** | empty | `1h30m` |
118+
| `--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` |
119+
| `--data` | Send data message instead of text (content in base64). | `false` | `true` |
120+
| `--data-port` | Destination port for data message (1 to 65535). | `53739` | `12345` |
121+
| `--skip-phone-validation` | Skip phone number validation. | `false` | `true` |
122+
| `--device-active-within` | Time window in hours for device activity filtering. `0` means no filtering. | `0` | `12` |
123+
124+
!!! note "Disabling booleans"
125+
To disable, use `--delivery-report=false`.
126+
127+
!!! tip
128+
For sending data messages, ensure the content is properly base64 encoded.
129+
Example: `echo -n 'hello world' | base64` → `aGVsbG8gd29ybGQ=`
97130

98131
---
99132

100-
#### Get the Status of a Message ⏱️
133+
#### Get Message Status
101134

102135
The `status` command retrieves the status of a message using its ID.
103136

@@ -106,11 +139,16 @@ The `status` command retrieves the status of a message using its ID.
106139
smsgate status 'Message ID'
107140
```
108141

142+
!!! note
143+
The status command requires the message ID returned from the `send` command.
144+
109145
---
110146

111-
### Webhooks Commands 🌐
147+
### Webhook Commands
112148

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

115153
The `register` command allows you to register a new webhook.
116154

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

167+
!!! important
168+
Ensure your webhook endpoint is accessible from the device and properly secured.
169+
129170
---
130171

131-
#### List Webhooks 📜
172+
#### List Webhooks
132173

133174
The `list` command displays all registered webhooks.
134175

@@ -137,9 +178,12 @@ The `list` command displays all registered webhooks.
137178
smsgate webhooks list
138179
```
139180

181+
!!! tip
182+
Use this command to audit your webhook configurations regularly.
183+
140184
---
141185

142-
#### Delete a Webhook 🗑️
186+
#### Delete Webhook
143187

144188
The `delete` command removes a webhook by its ID.
145189

@@ -148,22 +192,41 @@ The `delete` command removes a webhook by its ID.
148192
smsgate webhooks delete 'Webhook ID'
149193
```
150194

151-
## Usage examples 💡
195+
!!! warning
196+
Deleting a webhook is irreversible. Ensure you no longer need the webhook before deleting it.
197+
198+
## Usage Examples 💡
199+
200+
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.
152201

153-
For security reasons, it is recommended to pass credentials using environment variables or a `.env` file.
202+
### Basic Operations
154203

155204
```bash
156205
# Send a message
157-
smsgate send --phone '+19162255887' 'Hello, Dr. Turk!'
206+
smsgate send --phones '+19162255887' 'Hello, Dr. Turk!'
158207

159208
# Send a message to multiple numbers
160-
smsgate send --phone '+19162255887' --phone '+19162255888' 'Hello, doctors!'
209+
smsgate send --phones '+19162255887' --phones '+19162255888' 'Hello, doctors!'
161210
# or
162211
smsgate send --phones '+19162255887,+19162255888' 'Hello, doctors!'
163212

213+
# Send a message with a specific device
214+
smsgate send --device-id 'DwWLuSmLbXvwzF8mbmTE8' --phones '+19162255887' 'Hello from specific device!'
215+
216+
# Send a data message
217+
smsgate send --data --data-port 12345 --phones '+19162255887' 'aGVsbG8gd29ybGQ='
218+
```
219+
220+
### Message Management
221+
222+
```bash
164223
# Get the status of a sent message
165224
smsgate status zXDYfTmTVf3iMd16zzdBj
225+
```
226+
227+
### Webhook Management
166228

229+
```bash
167230
# Register a webhook for received messages
168231
smsgate webhooks register --event 'sms:received' 'https://example.com/webhook'
169232

@@ -174,24 +237,31 @@ smsgate webhooks list
174237
smsgate webhooks delete 'webhook-id'
175238
```
176239

240+
### Alternative Credential Methods
241+
177242
Credentials can also be passed via CLI options:
178243

179244
```bash
180245
# Pass credentials by options
181246
smsgate send -u <username> -p <password> \
182-
--phone '+19162255887' 'Hello, Dr. Turk!'
247+
--phones '+19162255887' 'Hello, Dr. Turk!'
183248
```
184249

250+
### Using Docker
251+
185252
If you prefer not to install the CLI tool locally, you can use Docker to run it:
186253

187254
```bash
188255
docker run -it --rm --env-file .env ghcr.io/android-sms-gateway/cli \
189-
send --phone '+19162255887' 'Hello, Dr. Turk!'
256+
send --phones '+19162255887' 'Hello, Dr. Turk!'
190257
```
191258

192-
## Exit codes 🔚
259+
!!! tip
260+
Using Docker is ideal for CI/CD pipelines or environments where you want to avoid local installations.
193261

194-
The CLI uses exit codes to indicate the outcome of operations:
262+
## Exit Codes 🔚
263+
264+
The CLI tool uses exit codes to indicate the outcome of operations. Properly handling these codes in scripts can improve error handling and automation.
195265

196266
| Code | Description |
197267
| ---- | --------------------- |
@@ -200,6 +270,12 @@ The CLI uses exit codes to indicate the outcome of operations:
200270
| 2 | 🌐 Network error |
201271
| 3 | 📄 Output format error |
202272

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

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

0 commit comments

Comments
 (0)