{"id":49888299,"url":"https://github.com/boxlinknet/kwtsms-cli","last_synced_at":"2026-05-15T19:33:48.890Z","repository":{"id":344122528,"uuid":"1180497139","full_name":"boxlinknet/kwtsms-cli","owner":"boxlinknet","description":"Command-line interface for the kwtSMS SMS gateway. Send SMS, check balance, and manage sender IDs from your terminal or automation pipeline.","archived":false,"fork":false,"pushed_at":"2026-03-13T14:36:28.000Z","size":99,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-13T16:18:15.716Z","etag":null,"topics":["ai-agent","automation","cli","devops","golang","kuwait","kwtsms","otp","sms","sms-gateway"],"latest_commit_sha":null,"homepage":"https://www.kwtsms.com/developers.html","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boxlinknet.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-13T05:16:17.000Z","updated_at":"2026-03-13T14:20:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/boxlinknet/kwtsms-cli","commit_stats":null,"previous_names":["boxlinknet/kwtsms-cli"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/boxlinknet/kwtsms-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boxlinknet%2Fkwtsms-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boxlinknet%2Fkwtsms-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boxlinknet%2Fkwtsms-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boxlinknet%2Fkwtsms-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boxlinknet","download_url":"https://codeload.github.com/boxlinknet/kwtsms-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boxlinknet%2Fkwtsms-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33076221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","automation","cli","devops","golang","kuwait","kwtsms","otp","sms","sms-gateway"],"created_at":"2026-05-15T19:33:48.001Z","updated_at":"2026-05-15T19:33:48.865Z","avatar_url":"https://github.com/boxlinknet.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kwtsms-cli\n\n[![Release](https://img.shields.io/github/v/release/boxlinknet/kwtsms-cli)](https://github.com/boxlinknet/kwtsms-cli/releases/latest)\n[![Build](https://img.shields.io/github/actions/workflow/status/boxlinknet/kwtsms-cli/release.yml?label=build)](https://github.com/boxlinknet/kwtsms-cli/actions)\n[![Downloads](https://img.shields.io/github/downloads/boxlinknet/kwtsms-cli/total)](https://github.com/boxlinknet/kwtsms-cli/releases)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/boxlinknet/kwtsms-cli)](https://go.dev)\n[![License](https://img.shields.io/github/license/boxlinknet/kwtsms-cli)](https://github.com/boxlinknet/kwtsms-cli/blob/main/LICENSE)\n[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-blue)](https://github.com/boxlinknet/kwtsms-cli/releases/latest)\n\nA command-line interface for the [kwtSMS](https://www.kwtsms.com) SMS gateway. Send SMS messages, check your account balance, and manage sender IDs, all from your terminal or as part of an automated workflow.\n\nDesigned for developers, DevOps engineers, and AI agents that need to integrate SMS delivery into scripts, pipelines, and automation without writing custom code.\n\n## About kwtSMS\n\n[kwtSMS](https://www.kwtsms.com) is a Kuwait-based SMS gateway trusted by businesses to deliver messages across Kuwait (Zain, Ooredoo, STC, Virgin) and internationally. It offers private Sender IDs, free API testing, non-expiring credits, and competitive flat-rate pricing. Open a free account in under one minute at [kwtsms.com/signup](https://www.kwtsms.com/signup/), no paperwork or payment required.\n\n## Use Cases\n\n- **SMS automation:** Send notifications, alerts, and reminders from shell scripts and cron jobs.\n- **AI agent integration:** Provide AI agents and LLM-powered tools with the ability to send SMS messages as a tool call.\n- **CI/CD pipelines:** Trigger SMS alerts on deployment, test failure, or system events.\n- **OTP delivery:** Send one-time passwords from any script or backend service.\n- **Balance monitoring:** Check remaining credits as part of a scheduled health check.\n\n## Installation\n\n### Direct download\n\nDownload the pre-built binary for your platform. No runtime required, just download and run.\n\n| Platform | Download |\n|---|---|\n| Linux x64 | [kwtsms-cli-linux-x64](https://github.com/boxlinknet/kwtsms-cli/releases/latest/download/kwtsms-cli-linux-x64) |\n| Linux ARM64 (Raspberry Pi 4/5) | [kwtsms-cli-linux-arm64](https://github.com/boxlinknet/kwtsms-cli/releases/latest/download/kwtsms-cli-linux-arm64) |\n| Linux ARMv7 (Raspberry Pi 2/3) | [kwtsms-cli-linux-armv7](https://github.com/boxlinknet/kwtsms-cli/releases/latest/download/kwtsms-cli-linux-armv7) |\n| macOS Intel | [kwtsms-cli-macos-x64](https://github.com/boxlinknet/kwtsms-cli/releases/latest/download/kwtsms-cli-macos-x64) |\n| macOS Apple Silicon | [kwtsms-cli-macos-arm64](https://github.com/boxlinknet/kwtsms-cli/releases/latest/download/kwtsms-cli-macos-arm64) |\n| Windows x64 | [kwtsms-cli-windows-x64.exe](https://github.com/boxlinknet/kwtsms-cli/releases/latest/download/kwtsms-cli-windows-x64.exe) |\n\n**Linux/macOS — install to PATH:**\n```bash\ncurl -Lo kwtsms-cli https://github.com/boxlinknet/kwtsms-cli/releases/latest/download/kwtsms-cli-linux-x64\nchmod +x kwtsms-cli\nsudo mv kwtsms-cli /usr/local/bin/\n```\n\n**Raspberry Pi (ARMv7):**\n```bash\ncurl -Lo kwtsms-cli https://github.com/boxlinknet/kwtsms-cli/releases/latest/download/kwtsms-cli-linux-armv7\nchmod +x kwtsms-cli\nsudo mv kwtsms-cli /usr/local/bin/\n```\n\n**Windows:** Download the `.exe` file and place it in a folder that is in your `PATH`.\n\n### Compile from source\n\nRequires only [Go](https://go.dev/dl/) installed. No other tools or system libraries needed.\n\n```bash\ngit clone https://github.com/boxlinknet/kwtsms-cli\ncd kwtsms-cli\ngo build -o kwtsms-cli .\n```\n\nWorks on any platform Go supports: Linux, macOS, Windows, and Raspberry Pi.\n\n## Quick Start\n\n```bash\n# Step 1: configure your credentials\nkwtsms-cli setup\n\n# Step 2: send your first message\nkwtsms-cli send --to 96598765432 --message \"Hello from kwtsms-cli\"\n\n# Check your balance\nkwtsms-cli balance\n```\n\n## Commands\n\n### `kwtsms-cli setup`\n\nInteractive wizard. Run once before using any other command.\n\nPrompts 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.\n\n```\nkwtSMS CLI Setup\n----------------\nAPI Username: myapiuser\nAPI Password: ••••••••••••••\n\nVerifying credentials...\n\nAvailable sender IDs:\n  [1] KWT-SMS\n  [2] MY-BRAND\n\nSelect default sender ID [1]: 2\n\nLog file [kwtsms-cli.log]\n(Enter for default, type path to change, \"none\" to disable):\n\nConfig saved to: /home/user/.config/kwtsms-cli/kwtsms-cli.toml\nLog file:        kwtsms-cli.log\n```\n\n### `kwtsms-cli balance`\n\nDisplay your current SMS credit balance.\n\n```bash\nkwtsms-cli balance\nkwtsms-cli balance --json\n```\n\n```\nAvailable:  1,234\nPurchased:  5,000\n```\n\n### `kwtsms-cli senderid`\n\nList all sender IDs approved on your account.\n\n```bash\nkwtsms-cli senderid\nkwtsms-cli senderid --json\n```\n\n### `kwtsms-cli coverage`\n\nList active country prefixes available for sending on your account.\n\n```bash\nkwtsms-cli coverage\nkwtsms-cli coverage --json\n```\n\n### `kwtsms-cli send`\n\nSend an SMS to one or more recipients.\n\n```bash\n# Single recipient\nkwtsms-cli send --to 96598765432 --message \"Your verification code is 4821\"\n\n# Multiple recipients (comma-separated)\nkwtsms-cli send --to 96598765432,96512345678 --message \"System maintenance tonight at 10pm\"\n\n# Multi-line message — use $'...' in bash so \\n becomes a real newline\nkwtsms-cli send --to 96598765432 --message $'Order confirmed\\nTracking: TRK-12345\\nExpected: Tomorrow'\n\n# Specify a sender ID\nkwtsms-cli send --to 96598765432 --message \"Your order is ready\" --sender MY-BRAND\n\n# Test mode: message is queued but not delivered, no credits consumed\nkwtsms-cli send --to 96598765432 --message \"Test\" --test\n```\n\n```\nSent\nNumbers:    1\nCharged:    1\nBalance:    1,234\nMsgID:      f4c841adee210f31307633ceaebff2ec\n```\n\n**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.\n\n```\nSent\nNumbers:    250\nCharged:    250\nBalance:    1,734\nMsgID:      bb6ceabbf187d0479a24eb0ea79edace\n            7793a77bc56ed1ff1bc0979c332cb98d\n```\n\nEstimated maximum recipients per platform (command-line argument size limit):\n\n| Platform | Estimated max |\n|---|---|\n| Linux / macOS | ~150,000 |\n| Windows | ~2,500 |\n\n**Flags:**\n\n| Flag | Required | Description |\n|---|---|---|\n| `-t, --to` | Yes | Recipient phone number(s), comma-separated. Duplicates removed automatically. |\n| `-m, --message` | Yes | Message text |\n| `-s, --sender` | No | Sender ID (overrides config default) |\n| `--test` | No | Queue without delivery, no credits used |\n\n## Global Flags\n\nAvailable on every command.\n\n| Flag | Description |\n|---|---|\n| `--json` | Output the raw API response as JSON, suitable for piping and scripting |\n| `--config PATH` | Use a different config file instead of the default |\n| `--username VALUE` | Override the API username for this call only |\n| `--password VALUE` | Override the API password for this call only |\n| `--version` | Print version and exit |\n\n## Configuration\n\n### Config file\n\n`kwtsms-cli setup` creates the config file automatically. You can also create or edit it manually.\n\n| Platform | Location |\n|---|---|\n| Linux / macOS | `~/.config/kwtsms-cli/kwtsms-cli.toml` |\n| Windows | `%APPDATA%\\kwtsms-cli\\kwtsms-cli.toml` |\n\n```toml\nusername = \"myapiuser\"\npassword = \"myapipass\"\nsender   = \"MY-BRAND\"\nlog_file = \"kwtsms-cli.log\"\n```\n\n### Environment variables\n\nUseful for CI/CD pipelines and containerised environments.\n\n```bash\nexport KWTSMS_USERNAME=myapiuser\nexport KWTSMS_PASSWORD=myapipass\nexport KWTSMS_SENDER=MY-BRAND\n```\n\n### Credential priority\n\nWhen the same value is set in multiple places, the highest priority source wins:\n\n```\n--username / --password flags  (highest)\nKWTSMS_USERNAME / KWTSMS_PASSWORD env vars\nconfig file                    (lowest)\n```\n\n## Phone Number Formats\n\nAll of the following formats are accepted. Numbers are automatically normalised before sending.\n\n```\n+96598765432     accepted, + prefix stripped\n0096598765432    accepted, 00 prefix stripped\n965 9876 5432    accepted, spaces stripped\n965-9876-5432    accepted, dashes stripped\n96598765432      correct format\n```\n\nArabic-Indic digits (`٩٦٥...`) are also accepted and converted automatically.\n\n## Logging\n\nWhen 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.\n\n```json\n{\"time\":\"2026-03-13T09:45:00Z\",\"numbers\":250,\"charged\":250,\"balance\":1,734,\"msg_ids\":[\"bb6ceabb...\",\"7793a77b...\"]}\n{\"time\":\"2026-03-13T09:50:00Z\",\"error\":\"[ERR011] Insufficient balance.\"}\n```\n\nThe `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.\n\n## AI Agent and Automation Usage\n\n### Agent Skill\n\nA ready-to-use skill file for Claude Code and other AI coding agents is included at [`skill/kwtsms-cli/SKILL.md`](skill/kwtsms-cli/SKILL.md). It covers:\n\n- Auto-detecting the correct binary for the running OS and architecture\n- Downloading and installing the binary\n- Configuring credentials via environment variables\n- All commands with expected output examples\n- Rules for safe agent use (always `--test` during development, credential handling, phone format)\n- Full error code reference\n\nTo 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.\n\n### Scripting\n\nkwtsms-cli is built for use in automated environments. Pair `--json` with any command for structured output that is easy to parse.\n\n**Send and capture the message ID:**\n```bash\nresult=$(kwtsms-cli send --to 96598765432 --message \"Alert: deploy complete\" --json)\nmsg_id=$(echo \"$result\" | jq -r '.\"msg-id\"')\n```\n\n**Check balance in a script:**\n```bash\navailable=$(kwtsms-cli balance --json | jq '.available')\nif [ \"$available\" -lt 100 ]; then\n  echo \"Low balance: $available credits remaining\"\nfi\n```\n\n**Use in a Makefile, cron job, or GitHub Actions workflow:**\n```yaml\n- name: Notify team via SMS\n  run: kwtsms-cli send --to 96598765432 --message \"Deploy complete: ${{ env.VERSION }}\"\n  env:\n    KWTSMS_USERNAME: ${{ secrets.KWTSMS_USERNAME }}\n    KWTSMS_PASSWORD: ${{ secrets.KWTSMS_PASSWORD }}\n    KWTSMS_SENDER: ${{ secrets.KWTSMS_SENDER }}\n```\n\n## Planned\n\n- **Homebrew formula:** `brew install kwtsms-cli` support for macOS.\n- **`go install` one-liner:** `go install github.com/boxlinknet/kwtsms-cli@latest` for Go developers.\n- **File input for bulk send:** `--file numbers.txt` to load recipients from a file.\n- **`validate` command:** Check phone numbers against the API before sending.\n- **`status` command:** Look up a sent message by its ID.\n\n## Support\n\n- Dashboard: [www.kwtsms.com/login](https://www.kwtsms.com/login)\n- General support and account questions: [www.kwtsms.com/support.html](https://www.kwtsms.com/support.html)\n- FAQ: [www.kwtsms.com/faq/](https://www.kwtsms.com/faq/)\n- Sender ID help: [www.kwtsms.com/sender-id-help.html](https://www.kwtsms.com/sender-id-help.html)\n\nFor security vulnerability reports, see [SECURITY.md](SECURITY.md).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboxlinknet%2Fkwtsms-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboxlinknet%2Fkwtsms-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboxlinknet%2Fkwtsms-cli/lists"}