Skip to content

Commit 154f199

Browse files
capcom6capcom6
committed
[ai] add SKILL.md
1 parent 3d4a331 commit 154f199

1 file changed

Lines changed: 251 additions & 0 deletions

File tree

‎SKILL.md‎

Lines changed: 251 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,251 @@
1+
---
2+
name: smsgate-cli
3+
description: >
4+
Use when you need to send SMS messages, manage webhooks, check delivery status,
5+
retrieve logs, or issue CA certificates via the SMS Gateway for Android API.
6+
Triggered on SMS sending, webhook management, message status checks, and log retrieval.
7+
license: Apache-2.0
8+
---
9+
10+
# SMSGate CLI
11+
12+
A CLI tool for interacting with the [SMS Gateway for Android](https://sms-gate.app) API. Ships two binaries:
13+
14+
- **`smsgate`** — send SMS, batch operations, manage webhooks, fetch logs
15+
- **`smsgate-ca`** — issue TLS certificates for private deployments
16+
17+
## Installation
18+
19+
### Option 1: GitHub Releases
20+
21+
Download the latest archive from the [Releases page](https://github.com/android-sms-gateway/cli/releases/latest). Archives are built with GoReleaser for Linux, macOS, and Windows. Each archive contains both `smsgate` and `smsgate-ca`.
22+
23+
Archive naming: `smsgate_Linux_x86_64.tar.gz`, `smsgate_Windows_x86_64.zip`, `smsgate_Darwin_arm64.tar.gz`, etc.
24+
25+
```bash
26+
# Use bash: extract archive and move binaries into PATH
27+
tar xzf smsgate_Linux_x86_64.tar.gz
28+
sudo mv smsgate smsgate-ca /usr/local/bin/
29+
```
30+
31+
### Option 2: Install using Go
32+
33+
```bash
34+
# Use bash: install via Go toolchain
35+
go install github.com/android-sms-gateway/cli/cmd/smsgate@latest
36+
go install github.com/android-sms-gateway/cli/cmd/smsgate-ca@latest
37+
```
38+
39+
> **Note**: Replace `@latest` with a specific version tag (e.g. `@v1.2.3`) for reproducible installs.
40+
41+
### Option 3: Docker
42+
43+
```bash
44+
# Use bash: run via Docker
45+
docker run -it --rm --env-file .env ghcr.io/android-sms-gateway/cli \
46+
send --phones '+12025550123' 'Hello!'
47+
```
48+
49+
The Docker image includes both `smsgate` (entrypoint) and `smsgate-ca`.
50+
51+
## Updating
52+
53+
- **Go**: Re-run the `go install` commands above with the target version tag.
54+
- **Docker**: `docker pull ghcr.io/android-sms-gateway/cli`
55+
56+
## Configuration
57+
58+
Credentials can be passed via CLI flags, environment variables, or a `.env` file.
59+
60+
| Flag | Env Var | Description | Default |
61+
|------|---------|-------------|---------|
62+
| `--endpoint`, `-e` | `ASG_ENDPOINT` | API endpoint URL | `https://api.sms-gate.app/3rdparty/v1` |
63+
| `--username`, `-u` | `ASG_USERNAME` | Username | required |
64+
| `--password`, `-p` | `ASG_PASSWORD` | Password | required |
65+
| `--format`, `-f` | — | Output format | `text` |
66+
67+
The `.env` file in the working directory is loaded automatically.
68+
69+
## Commands
70+
71+
### `smsgate send`
72+
73+
Send a text or data (binary) SMS message.
74+
75+
```bash
76+
smsgate send [flags] <message>
77+
```
78+
79+
| Flag | Description | Default |
80+
|------|-------------|---------|
81+
| `--phones`, `-p` | Recipient phone number(s), E.164 format (repeatable or comma-separated) | required |
82+
| `--id` | Custom message ID | auto-generated |
83+
| `--device-id`, `--device` | Specific device ID | auto |
84+
| `--sim-number`, `--sim` | SIM slot (one-based) | device default |
85+
| `--delivery-report` | Enable delivery report | `true` |
86+
| `--priority` | Priority (-128 to 127; >= 100 bypasses limits) | `0` |
87+
| `--ttl` | Time-to-live (e.g. `1h30m`) | unlimited |
88+
| `--valid-until` | Expiration time (RFC3339) | unlimited |
89+
| `--schedule-at` | Schedule delivery time (RFC3339) | immediate |
90+
| `--skip-phone-validation` | Skip phone validation | `false` |
91+
| `--device-active-within` | Filter by device activity (hours) | `0` (no filter) |
92+
| `--data` | Send data message (content must be base64) | `false` |
93+
| `--data-port` | Destination port for data message | `53739` |
94+
95+
### `smsgate status`
96+
97+
Check the delivery state of a sent message.
98+
99+
```bash
100+
smsgate status <message-id>
101+
```
102+
103+
### `smsgate batch send`
104+
105+
Send messages in bulk from a CSV or XLSX file.
106+
107+
```bash
108+
smsgate batch send [flags] <filename>
109+
```
110+
111+
| Flag | Description | Default |
112+
|------|-------------|---------|
113+
| `--map` | Column mapping: `phone=Col,text=Col` (comma-separated) | required |
114+
| `--sheet` | Sheet name (XLSX only) | first sheet |
115+
| `--delimiter` | CSV delimiter | `,` |
116+
| `--header` | Treat first row as header | `true` |
117+
| `--dry-run` | Validate and preview without sending | `false` |
118+
| `--validate-only` | Validate input only (no preview) | `false` |
119+
| `--concurrency` | Number of concurrent workers | CPU cores |
120+
| `--continue-on-error` | Continue after per-row failures | `false` |
121+
122+
Also accepts the shared flags from `send` (`--device-id`, `--sim-number`, `--priority`, `--ttl`, `--valid-until`, `--delivery-report`, `--skip-phone-validation`, `--device-active-within`), applied to every message in the batch.
123+
124+
**Column mapping fields:**
125+
126+
| Field | Required | Description |
127+
|-------|----------|-------------|
128+
| `phone` | yes | Phone number |
129+
| `text` | yes | Message text |
130+
| `id` | no | Custom message ID |
131+
| `device_id` | no | Device identifier |
132+
| `sim_number` | no | SIM slot number |
133+
| `priority` | no | Message priority |
134+
135+
**Workflow modes:**
136+
137+
1. **Validate only** — check file and mapping: `--validate-only`
138+
2. **Dry run** — preview all parsed rows: `--dry-run`
139+
3. **Full send** — send with progress: `--concurrency=5`
140+
141+
### `smsgate webhooks`
142+
143+
Manage webhooks for event notifications.
144+
145+
```bash
146+
# Register a webhook
147+
smsgate webhooks register --event <event> [--id ID] [--device-id DEVICE] <url>
148+
149+
# List all webhooks
150+
smsgate webhooks list
151+
152+
# Delete a webhook
153+
smsgate webhooks delete <id>
154+
```
155+
156+
Events: `sms:received`, `sms:sent`, `sms:failed`, `device:connected`, `device:disconnected`
157+
158+
### `smsgate logs`
159+
160+
Retrieve logs within a time range.
161+
162+
```bash
163+
smsgate logs [--from TIME] [--to TIME]
164+
```
165+
166+
Dates use RFC3339 format (e.g. `2024-01-15T10:30:00Z`). Defaults to the last 24 hours.
167+
168+
### `smsgate-ca`
169+
170+
Issue TLS certificates for private SMS Gateway deployments.
171+
172+
```bash
173+
smsgate-ca [--timeout DURATION] webhooks [--out FILE] [--keyout FILE] <ip-address>
174+
smsgate-ca [--timeout DURATION] private [--out FILE] [--keyout FILE] <ip-address>
175+
```
176+
177+
| Flag | Description | Default |
178+
|------|-------------|---------|
179+
| `--timeout`, `-t` | Request timeout | `30s` |
180+
| `--out` | Certificate output file | `server.crt` |
181+
| `--keyout` | Private key output file | `server.key` |
182+
183+
The IP address must be a private (RFC 1918) address.
184+
185+
## Output Formats
186+
187+
All commands support `--format` (or `-f`) with four options:
188+
189+
- **`text`** — human-readable key:value pairs (default)
190+
- **`json`** — pretty-printed JSON
191+
- **`raw`** — compact one-line JSON
192+
- **`table`** — tab-aligned columns
193+
194+
Error messages are always printed to stderr in plain text regardless of format.
195+
196+
## Exit Codes
197+
198+
| Code | Meaning |
199+
|------|---------|
200+
| 0 | Success |
201+
| 1 | Invalid options or arguments |
202+
| 2 | Server request error |
203+
| 3 | Output formatting error |
204+
| 4 | Internal error |
205+
206+
## Examples
207+
208+
```bash
209+
# Send a text message
210+
smsgate send --phones '+12025550123' 'Hello, Dr. Turk!'
211+
212+
# Send to multiple phones
213+
smsgate send --phones '+12025550123,+12025550124' 'Hello!'
214+
215+
# Send with priority (bypasses limits)
216+
smsgate send --phones '+12025550123' --priority 100 'Urgent'
217+
218+
# Send a data message
219+
echo -n 'hello' | base64
220+
smsgate send --phones '+12025550123' --data --data-port 12345 'aGVsbG8='
221+
222+
# Check message status
223+
smsgate status zXDYfTmTVf3iMd16zzdBj
224+
225+
# Batch send from CSV
226+
smsgate batch send contacts.csv --map phone=Phone,text=Message
227+
228+
# Batch send from XLSX with a specific sheet
229+
smsgate batch send campaign.xlsx --sheet Sheet1 --map phone=Phone,text=Message
230+
231+
# Dry-run batch (validate + preview)
232+
smsgate batch send contacts.csv --map phone=Phone,text=Message --dry-run
233+
234+
# Register a webhook
235+
smsgate webhooks register --event sms:received https://example.com/hook
236+
237+
# List webhooks (table format)
238+
smsgate --format table webhooks list
239+
240+
# Delete a webhook
241+
smsgate webhooks delete wh_abc123
242+
243+
# Get logs for a specific time range
244+
smsgate logs --from '2024-01-15T00:00:00Z' --to '2024-01-15T23:59:59Z'
245+
246+
# Issue a CA certificate for webhooks
247+
smsgate-ca webhooks 192.168.1.100 --out server.crt --keyout server.key
248+
249+
# Issue a CA certificate for a private server
250+
smsgate-ca private 10.0.0.5 --out myserver.crt --keyout myserver.key
251+
```

0 commit comments

Comments
 (0)