@k-msg/cli 0.5.8 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @k-msg/cli
 
+## 0.6.1 — 2026-02-18
+
+### Patch changes
+
+- [19e519f](https://github.com/k-otp/k-msg/commit/19e519f0edcb4f3a00d07f090046f30ac5c5e87b) Harden CLI/core reliability by making option parsing deterministic (`--flag`/`--no-flag` with strict boolean validation), aligning provider error payloads to `details`, and migrating the send contract field to `templateId` (without compatibility aliases) with matching docs/tests and canonical CI parity checks. — Thanks @imjlk!
+- [aafac43](https://github.com/k-otp/k-msg/commit/aafac43c09c7b95a0a50af610662c91cbc4e6c76) Remove duplicated CLI provider config metadata by sourcing labels, routing seed types, and recommended defaults from `@k-msg/provider`. Also update template option wording to `Template ID` and fix root breaking-change notes to `templateCode -> templateId`. — Thanks @imjlk!
+- Updated dependencies: core@0.18.2, messaging@0.18.2, provider@0.18.2, k-msg@0.18.2
+
+## 0.6.0 — 2026-02-18
+
+### Minor changes
+
+- [a63307e](https://github.com/k-otp/k-msg/commit/a63307eb4a925343b74297b8437f72caba587dff) Improve CLI send usability by clarifying raw-JSON advanced usage, adding `k-msg send --dry-run` preview mode (without provider send), and enhancing batch/error output guidance. — Thanks @imjlk!
+- [48f2797](https://github.com/k-otp/k-msg/commit/48f27975b5734c760f5ec99701623865f28d8c8c) Feat: support batch sending via `k-msg send --input '[...]'` and persistence configuration (`strategy`, `repo`) in `k-msg.config.json`. — Thanks @imjlk!
+
+### Patch changes
+
+- Updated dependencies: core@0.18.1, provider@0.18.1, k-msg@0.18.1
+
 ## 0.5.8 — 2026-02-17
 
 ### Patch changes

package/README.md

@@ -123,6 +123,50 @@ k-msg config provider add iwinv
 Any string value like `"env:NAME"` is replaced with the `NAME` environment variable at runtime.
 If the env var is missing/empty, commands that need runtime providers will fail with exit code `2`.
 
+### Provider send value guide
+
+When you are unsure which values must be prepared before send, use this checklist:
+
+1. Configure provider credentials with `env:` references.
+2. Run `k-msg providers doctor` to verify account/config readiness.
+3. For AlimTalk, run `k-msg alimtalk preflight` with the provider/template/channel you will use.
+4. Send only after preflight passes.
+
+Credential examples:
+
+```bash
+# Aligo
+export ALIGO_API_KEY="..."
+export ALIGO_USER_ID="..."
+export ALIGO_SENDER_KEY="..."   # Kakao senderKey
+export ALIGO_SENDER="029302266" # SMS/LMS sender
+
+# IWINV
+export IWINV_API_KEY="..."          # AlimTalk key
+export IWINV_SMS_API_KEY="..."      # SMS/LMS/MMS key
+export IWINV_SMS_AUTH_KEY="..."     # SMS/LMS/MMS secret
+export IWINV_SMS_COMPANY_ID="..."   # status/balance context
+export IWINV_SENDER_NUMBER="029302266"
+
+# SOLAPI
+export SOLAPI_API_KEY="..."
+export SOLAPI_API_SECRET="..."
+export SOLAPI_DEFAULT_FROM="029302266"
+export SOLAPI_KAKAO_PF_ID="..."     # Kakao profileId(pfId)
+```
+
+Required values by provider/channel:
+
+| Provider | Channel | Required config keys | Required send-time values | Notes |
+| --- | --- | --- | --- | --- |
+| `aligo` | `SMS/LMS/MMS` | `apiKey`, `userId` | `to`, `text`, sender (`--from` or `aligo.config.sender`) | MMS also needs image input |
+| `aligo` | `ALIMTALK` | `apiKey`, `userId` | `to`, `template-id`, `vars`, senderKey (`--sender-key`/`--channel` alias/`aligo.config.senderKey`), sender (`--from` or `aligo.config.sender`) | `preflight` validates channel/template access |
+| `iwinv` | `SMS/LMS/MMS` | `apiKey`, `smsApiKey`, `smsAuthKey` | `to`, `text`, sender (`--from` or `iwinv.config.smsSenderNumber`/`senderNumber`) | MMS requires image binary input |
+| `iwinv` | `ALIMTALK` | `apiKey` | `to`, `template-id`, `vars` | If failover/reSend is enabled, sender callback is required (`--from` or sender number in config) |
+| `solapi` | `SMS/LMS/MMS` | `apiKey`, `apiSecret` | `to`, `text`, sender (`--from` or `solapi.config.defaultFrom`) | MMS also needs image input |
+| `solapi` | `ALIMTALK` | `apiKey`, `apiSecret` | `to`, `template-id`, `vars`, profileId/pfId (`--sender-key`/channel alias or `solapi.config.kakaoPfId`) | For preflight policy checks, set `plusId` via `--plus-id` or channel/default alias |
+| `mock` | all | none | minimal message fields (`to`, `text` or `template-id`/`vars`) | Local test provider |
+
 ## Commands
 
 - `k-msg config init|show|validate`
@@ -130,7 +174,7 @@ If the env var is missing/empty, commands that need runtime providers will fail
 - `k-msg providers list|health|doctor`
 - `k-msg sms send`
 - `k-msg alimtalk preflight|send`
-- `k-msg send --input <json> | --file <path> | --stdin`
+- `k-msg send --input <json> | --file <path> | --stdin` (advanced/raw JSON only)
 - `k-msg kakao channel categories|list|auth|add`
 - `k-msg kakao template list|get|create|update|delete|request`
 
@@ -142,8 +186,8 @@ If the env var is missing/empty, commands that need runtime providers will fail
 
 ```bash
 k-msg providers doctor
-k-msg alimtalk preflight --provider iwinv --template-code TPL_001 --channel main
-k-msg alimtalk send --provider iwinv --template-code TPL_001 --to 01012345678 --vars '{"name":"Jane"}'
+k-msg alimtalk preflight --provider iwinv --template-id TPL_001 --channel main
+k-msg alimtalk send --provider iwinv --template-id TPL_001 --to 01012345678 --vars '{"name":"Jane"}'
 ```
 
 Notes:
@@ -166,7 +210,7 @@ Terminology: the CLI uses **Kakao Channel** and **senderKey** (never “profile
 ```bash
 k-msg alimtalk send \
   --to 01012345678 \
-  --template-code TPL_001 \
+  --template-id TPL_001 \
   --vars '{"name":"Jane"}' \
   --channel main \
   --plus-id @my_channel
@@ -177,7 +221,7 @@ Failover options:
 ```bash
 k-msg alimtalk send \
   --to 01012345678 \
-  --template-code TPL_001 \
+  --template-id TPL_001 \
   --vars '{"name":"Jane"}' \
   --failover true \
   --fallback-channel sms \
@@ -192,7 +236,7 @@ When providers return send warnings (for example failover partial/unsupported),
 ```bash
 k-msg alimtalk preflight \
   --provider iwinv \
-  --template-code TPL_001 \
+  --template-id TPL_001 \
   --channel main \
   --sender-key your_sender_key \
   --plus-id @my_channel
@@ -202,10 +246,42 @@ k-msg alimtalk preflight \
 
 ### Advanced JSON send
 
+`k-msg send` is an advanced command for raw `SendInput` JSON (object or array).
+For common workflows, prefer `k-msg sms send` and `k-msg alimtalk send`.
+
 ```bash
 k-msg send --input '{"to":"01012345678","text":"hello"}'
 ```
 
+Single preview without sending:
+
+```bash
+k-msg send --input '{"to":"01012345678","text":"hello"}' --dry-run
+```
+
+Batch preview without sending:
+
+```bash
+k-msg send --input '[{"to":"01011112222","text":"hello 1"},{"to":"01033334444","text":"hello 2"}]' --dry-run
+```
+
+`providers doctor` and `send --dry-run` have different roles:
+
+- `k-msg providers doctor`: provider/account/capability readiness checks
+- `k-msg send --dry-run`: request payload preview/validation (no provider send)
+
+Boolean flag semantics (applies to `--json`, `--verbose`, `--dry-run`, `--stdin`, `--failover`, `--force`):
+
+- `--flag` -> `true`
+- `--flag true` -> `true`
+- `--flag false` -> `false`
+- `--no-flag` -> `false`
+- Invalid boolean values (for example `--dry-run maybe`) fail with exit code `2`
+
+Resolution precedence for overlapping values is:
+
+- `CLI flag > environment variable > config file > built-in default`
+
 ## Kakao Channel (Aligo capability)
 
 ```bash
@@ -226,13 +302,13 @@ Channel scope (Aligo): use `--channel <alias>` or `--sender-key <value>`.
 
 ```bash
 k-msg kakao template list
-k-msg kakao template get --template-code TPL_001
+k-msg kakao template get --template-id TPL_001
 k-msg kakao template create --name "Welcome" --content "Hello #{name}" --channel main
-k-msg kakao template update --template-code TPL_001 --name "Updated"
-k-msg kakao template delete --template-code TPL_001
+k-msg kakao template update --template-id TPL_001 --name "Updated"
+k-msg kakao template delete --template-id TPL_001
 
 # inspection request is provider-dependent (supported by Aligo)
-k-msg kakao template request --template-code TPL_001 --channel main
+k-msg kakao template request --template-id TPL_001 --channel main
 ```
 
 ## Output / Exit Codes
@@ -242,6 +318,7 @@ k-msg kakao template request --template-code TPL_001 --channel main
   when an agent is detected (`CLAUDECODE`, `CURSOR_AGENT`, `CODEX_CI` /
   `CODEX_SHELL` / `CODEX_THREAD_ID`, `MCP_SERVER_NAME` / `MCP_SESSION_ID` /
   `MCP_TOOL_NAME`)
+- Force text output in AI environments with `--json false` (or `--no-json`)
 - exit code:
   - `0`: success
   - `2`: input/config error

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-msg/cli",
-  "version": "0.5.8",
+  "version": "0.6.1",
   "private": false,
   "description": "k-msg CLI (prebuilt binaries via GitHub Releases)",
   "type": "module",
@@ -26,6 +26,7 @@
     "build:native": "bunli build --targets native",
     "build:js": "bun run generate && bun build src/k-msg.ts --outdir=dist --format=esm --target=bun",
     "dev": "bun run generate && bun --watch src/k-msg.ts",
+    "typecheck": "bun run generate && tsc --noEmit -p tsconfig.json",
     "test": "bun run generate && bun test",
     "schema:generate": "bun run scripts/generate-config-schema.ts",
     "schema:check": "bun run scripts/generate-config-schema.ts --check",
@@ -33,6 +34,7 @@
   },
   "devDependencies": {
     "@k-msg/core": "0.17.0",
+    "@k-msg/messaging": "0.17.0",
     "@k-msg/provider": "0.17.0",
     "@bunli/core": "^0.5.4",
     "@bunli/plugin-ai-detect": "^0.5.2",