Skip to content

About

Command-line interface for the kwtSMS SMS gateway. Send SMS, check balance, and manage sender IDs from your terminal or automation pipeline.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

kwtSMS: SMS gateway for Kuwait

kwtSMS CLI

Release Build Downloads Go Version License Platform

Send SMS, check your balance, validate numbers and list Sender IDs from your terminal, scripts and CI pipelines, through kwtSMS, the Kuwaiti SMS gateway. Free, one binary, no runtime. The command is kwtsms-cli.

kwtSMS delivers to Zain, Ooredoo, stc and Virgin in Kuwait and to more than 200 countries, with your own Sender ID, free API testing and credits that do not expire.

Designed for developers, DevOps engineers, and AI agents that need to integrate SMS delivery into scripts, pipelines, and automation without writing custom code.

Requirements

A kwtSMS account (free test account, no papers): https://www.kwtsms.com/cportal/signup/

Test mode: send --test queues the message and does not deliver it. Its credits are held until you delete it from the Sending Queue.

Use Cases

  • SMS automation: Send notifications, alerts, and reminders from shell scripts and cron jobs.
  • AI agent integration: Give AI coding agents that run in a terminal a safe way to send SMS: the login is stored once by kwtsms-cli setup, never typed into commands. For AI chat apps use the kwtSMS MCP server instead.
  • CI/CD pipelines: Trigger SMS alerts on deployment, test failure, or system events.
  • OTP delivery: Send one-time passwords from any script or backend service.
  • Balance monitoring: Check remaining credits as part of a scheduled health check.

Installation

Direct download

Download the pre-built binary for your platform. No runtime required, just download and run.

Platform Download
Linux x64 kwtsms-cli-linux-x64
Linux ARM64 (Raspberry Pi 4/5) kwtsms-cli-linux-arm64
Linux ARMv7 (Raspberry Pi 2/3) kwtsms-cli-linux-armv7
macOS Intel kwtsms-cli-macos-x64
macOS Apple Silicon kwtsms-cli-macos-arm64
Windows x64 kwtsms-cli-windows-x64.exe

Linux/macOS: install to PATH:

curl -Lo kwtsms-cli https://github.com/kwtsms/kwtsms-cli/releases/latest/download/kwtsms-cli-linux-x64
chmod +x kwtsms-cli
sudo mv kwtsms-cli /usr/local/bin/

Raspberry Pi (ARMv7):

curl -Lo kwtsms-cli https://github.com/kwtsms/kwtsms-cli/releases/latest/download/kwtsms-cli-linux-armv7
chmod +x kwtsms-cli
sudo mv kwtsms-cli /usr/local/bin/

Windows: Download the .exe file and place it in a folder that is in your PATH.

Compile from source

Requires only Go installed. No other tools or system libraries needed.

git clone https://github.com/kwtsms/kwtsms-cli
cd kwtsms-cli
go build -o kwtsms-cli .

Works on any platform Go supports: Linux, macOS, Windows, and Raspberry Pi.

Quick Start

# Step 1: configure your credentials
kwtsms-cli setup

# Step 2: send your first message
kwtsms-cli send --to 965XXXXXXXX --message "Hello from kwtsms-cli"

# Check your balance
kwtsms-cli balance

Commands

kwtsms-cli setup

Interactive wizard. Run once before using any other command.

Prompts for API username, password, default sender ID, and log file. Verifies credentials against the API before saving anything. Writes the config file to the platform-appropriate location.

kwtSMS CLI Setup
----------------
API Username: myapiuser
API Password: ••••••••••••••

Verifying credentials...

Available sender IDs:
  [1] KWT-SMS
  [2] MY-BRAND

Select default sender ID [1]: 2

Log file [kwtsms-cli.log]
(Enter for default, type path to change, "none" to disable):

Config saved to: /home/user/.config/kwtsms-cli/kwtsms-cli.toml
Log file:        kwtsms-cli.log

kwtsms-cli balance

Display your current SMS credit balance.

kwtsms-cli balance
kwtsms-cli balance --json
Available:  1,234
Purchased:  5,000

kwtsms-cli senderid

List all sender IDs approved on your account.

kwtsms-cli senderid
kwtsms-cli senderid --json

kwtsms-cli coverage

List active country prefixes available for sending on your account.

kwtsms-cli coverage
kwtsms-cli coverage --json

kwtsms-cli validate

Check numbers for format and route before sending. Nothing is sent and no credits are used. Up to 2500 numbers per call.

kwtsms-cli validate -t 965XXXXXXXX,965YYYYYYYY
kwtsms-cli validate -t 965XXXXXXXX --json
Valid (OK): 1
  965XXXXXXXX
Invalid format (ER): 0
No route (NR): 1
  965YYYYYYYY

OK = valid and routable, ER = format error, NR = no route (country not activated on your account).

kwtsms-cli status

Show the queue status of a sent message by its msg-id (from the send output). This is the queue status (pending, error in queue, or sent to the gateway), not a delivery report.

kwtsms-cli status f4c841adee210f31307633ceaebff2ec
kwtsms-cli status f4c841adee210f31307633ceaebff2ec --json
Status:      sent
Description: Message successfully sent to gateway

kwtsms-cli dlr

Show per-number delivery reports for a sent message. Delivery reports exist for international numbers only: Kuwait numbers do not return them. Wait at least 5 minutes after sending, and add a delay between calls if you poll in bulk, or your IP may be blocked.

kwtsms-cli dlr f4c841adee210f31307633ceaebff2ec
kwtsms-cli dlr f4c841adee210f31307633ceaebff2ec --json
965XXXXXXXX  Received by recipient

kwtsms-cli version-check

Compare the installed version with the latest GitHub release. No credentials needed.

kwtsms-cli version-check
kwtsms-cli version-check --json

kwtsms-cli send

Send an SMS to one or more recipients.

# Single recipient
kwtsms-cli send --to 965XXXXXXXX --message "Your verification code is 4821"

# Multiple recipients (comma-separated)
kwtsms-cli send --to 965XXXXXXXX,965YYYYYYYY --message "System maintenance tonight at 10pm"

# Multi-line message: use $'...' in bash so \n becomes a real newline
kwtsms-cli send --to 965XXXXXXXX --message $'Order confirmed\nTracking: TRK-12345\nExpected: Tomorrow'

# Specify a sender ID
kwtsms-cli send --to 965XXXXXXXX --message "Your order is ready" --sender MY-BRAND

# Test mode: queued, not delivered; credits held until you delete it from the Sending Queue
kwtsms-cli send --to 965XXXXXXXX --message "Test" --test
Sent
Numbers:    1
Charged:    1
Balance:    1,234
MsgID:      f4c841adee210f31307633ceaebff2ec

Bulk sending: any number of recipients is accepted. Batches larger than 200 are split automatically into groups of 200 with a 500ms delay between batches. Numbers and Charged are aggregated in the output, with one MsgID per batch.

Sent
Numbers:    250
Charged:    250
Balance:    1,734
MsgID:      bb6ceabbf187d0479a24eb0ea79edace
            7793a77bc56ed1ff1bc0979c332cb98d

Estimated maximum recipients per platform (command-line argument size limit):

Platform Estimated max
Linux / macOS ~150,000
Windows ~2,500

Flags:

Flag Required Description
-t, --to Yes Recipient phone number(s), comma-separated. Duplicates removed automatically.
-m, --message Yes Message text
-s, --sender No Sender ID (overrides config default)
--test No Queued, not delivered; credits held until you delete it from the Sending Queue

Global Flags

Available on every command.

Flag Description
--json Output the raw API response as JSON, suitable for piping and scripting
--config PATH Use a different config file instead of the default
--username VALUE Override the API username for this call only
--password VALUE Override the API password for this call only
--version Print version and exit

Configuration

Config file

kwtsms-cli setup creates the config file automatically. You can also create or edit it manually.

Platform Location
Linux / macOS ~/.config/kwtsms-cli/kwtsms-cli.toml
Windows %APPDATA%\kwtsms-cli\kwtsms-cli.toml
username = "myapiuser"
password = "myapipass"
sender   = "MY-BRAND"
log_file = "kwtsms-cli.log"

Environment variables

Useful for CI/CD pipelines and containerised environments.

export KWTSMS_USERNAME=myapiuser
export KWTSMS_PASSWORD=myapipass
export KWTSMS_SENDER=MY-BRAND

Credential priority

When the same value is set in multiple places, the highest priority source wins:

--username / --password flags  (highest)
KWTSMS_USERNAME / KWTSMS_PASSWORD env vars
config file                    (lowest)

Phone Number Formats

All of the following formats are accepted. Numbers are automatically normalised before sending.

+965XXXXXXXX     accepted, + prefix stripped
00965XXXXXXXX    accepted, 00 prefix stripped
+965 XXXX XXXX   accepted, spaces stripped
965-XXXX-XXXX    accepted, dashes stripped
965XXXXXXXX      correct format

Arabic-Indic digits (٩٦٥...) are also accepted and converted automatically.

Logging

When a log file is configured, every send call appends one JSON line to the file. The log records the timestamp, number of recipients, credits charged, balance after, and all message IDs. Credentials, phone numbers, and message text are never written to the log.

{"time":"2026-03-13T09:45:00Z","numbers":250,"charged":250,"balance":1,734,"msg_ids":["bb6ceabb...","7793a77b..."]}
{"time":"2026-03-13T09:50:00Z","error":"[ERR011] Insufficient balance."}

The log_file value in the config is a filename relative to the directory where you run the binary. To disable logging, remove the log_file line from the config or set it to an empty string. You can also reconfigure it at any time by running kwtsms-cli setup again.

AI Agent and Automation Usage

Agent Skill

A ready-to-use skill file for Claude Code and other AI coding agents is included at skill/kwtsms-cli/SKILL.md. It covers:

  • Auto-detecting the correct binary for the running OS and architecture
  • Downloading and installing the binary
  • Configuring credentials via environment variables
  • All commands with expected output examples
  • Rules for safe agent use (always --test during development, credential handling, phone format)
  • Full error code reference

To use it in Claude Code, add the skill to your project and the agent will know how to install and operate kwtsms-cli without additional instructions.

Scripting

kwtsms-cli is built for use in automated environments. Pair --json with any command for structured output that is easy to parse.

Send and capture the message ID:

result=$(kwtsms-cli send --to 965XXXXXXXX --message "Alert: deploy complete" --json)
msg_id=$(echo "$result" | jq -r '."msg-id"')

Check balance in a script:

available=$(kwtsms-cli balance --json | jq '.available')
if [ "$available" -lt 100 ]; then
  echo "Low balance: $available credits remaining"
fi

Use in a Makefile, cron job, or GitHub Actions workflow:

- name: Notify team via SMS
  run: kwtsms-cli send --to 965XXXXXXXX --message "Deploy complete: ${{ env.VERSION }}"
  env:
    KWTSMS_USERNAME: ${{ secrets.KWTSMS_USERNAME }}
    KWTSMS_PASSWORD: ${{ secrets.KWTSMS_PASSWORD }}
    KWTSMS_SENDER: ${{ secrets.KWTSMS_SENDER }}

Planned

  • Homebrew formula: brew install kwtsms-cli support for macOS.
  • go install one-liner: go install github.com/kwtsms/kwtsms-cli@latest for Go developers.
  • File input for bulk send: --file numbers.txt to load recipients from a file.

Arabic

Arabic message text is sent as is, and Arabic-Indic digits in phone numbers are converted to Latin digits.

kwtsms-cli send --to 965XXXXXXXX --message "مرحبا، رمز التحقق 4821" --test

FAQ

Which username do I use?

The API username and password of your kwtSMS account, not your mobile number. Run kwtsms-cli setup once to store them.

Why do test messages not arrive?

send --test queues the message without delivering it. Its credits are held until you delete it from the Sending Queue. Leave out --test to send for real.

What is a Sender ID?

The name shown as the sender on the phone. See the Sender ID help.

Can I send to international numbers?

Yes, but international sending is off by default. To turn a country on, log in to your kwtSMS account, go to Coverage, click Add, choose the country and fill in the form. Requests are usually reviewed the same day. API error ERR026 means the country is not active on your account yet: contact support to add it.

Rules in short:

  • Transactional messages only (OTP, payment links). No bulk or promotional messages.
  • The Sender ID abroad is KWT-SMS. You can register your own Sender ID in a country only if you hold an active business license in that country (same name as in Kuwait).
  • Many networks abroad filter messages with links, and the credits are still deducted.
  • International traffic has limits (share of your traffic, warnings and a daily maximum). International coverage also raises your exposure to bot abuse, so protect your OTP and sign-up forms (CAPTCHA, rate limits).
  • Credits: today every SMS part uses 1 credit, to any country.

Current rules, limits and credits per country: https://www.kwtsms.com/faq/send-international-sms-messages.html

Changelog

See CHANGELOG.md.

Support

Help: https://www.kwtsms.com/support.html | FAQ: https://www.kwtsms.com/faq/ | API: developers, API reference | Issues

Security

See SECURITY.md.

License

MIT, (c) kwtSMS (BoxLink Center). See LICENSE.

About

Command-line interface for the kwtSMS SMS gateway. Send SMS, check balance, and manage sender IDs from your terminal or automation pipeline.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages