@siwats/ssa 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +109 -2
- package/dist/bin.mjs +6429 -0
- package/package.json +34 -5
package/README.md
CHANGED
|
@@ -1,3 +1,110 @@
|
|
|
1
|
-
#
|
|
1
|
+
# ssa: SIWAT SYSTEM Portal CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A terminal and scripting front end for the portal API. Run it from the repo
|
|
4
|
+
with `bun run apps/cli/bin.ts <args>` (or `bun run dev -- <args>` inside
|
|
5
|
+
`apps/cli`).
|
|
6
|
+
|
|
7
|
+
## Signing in
|
|
8
|
+
|
|
9
|
+
ssa auth login # SSO in the browser, or paste an API key
|
|
10
|
+
ssa auth whoami
|
|
11
|
+
|
|
12
|
+
For cron jobs and agents skip the login and set credentials in the environment:
|
|
13
|
+
|
|
14
|
+
SSA_BASE=https://portal.siwatsystem.com SSA_TOKEN=... ssa auth whoami
|
|
15
|
+
|
|
16
|
+
Precedence: `--base`/`--token` flags, then `SSA_BASE`/`SSA_TOKEN`, then the
|
|
17
|
+
saved login in `~/.config/ssa-cli/config.json` (mode 0600). The saved token is
|
|
18
|
+
only sent to the saved portal; `--base other-host` without a token fails with
|
|
19
|
+
exit 3 rather than sending it elsewhere.
|
|
20
|
+
|
|
21
|
+
## Output
|
|
22
|
+
|
|
23
|
+
On a terminal you get a table or key/value block. Piped, or with `--json`, you
|
|
24
|
+
get JSON on stdout. Prompts, progress and errors always go to stderr.
|
|
25
|
+
|
|
26
|
+
## Exit codes
|
|
27
|
+
|
|
28
|
+
| Code | Meaning |
|
|
29
|
+
|------|---------|
|
|
30
|
+
| 0 | ok |
|
|
31
|
+
| 1 | generic failure (including a declined confirmation) |
|
|
32
|
+
| 2 | usage error: unknown command, bad flag value, refused unconfirmed delete |
|
|
33
|
+
| 3 | not logged in, or HTTP 401 |
|
|
34
|
+
| 4 | forbidden (HTTP 403) |
|
|
35
|
+
| 5 | not found (HTTP 404) |
|
|
36
|
+
| 6 | server or network error (HTTP 5xx, unreachable portal) |
|
|
37
|
+
|
|
38
|
+
## Destructive commands
|
|
39
|
+
|
|
40
|
+
Commands that delete or interrupt something ask `[y/N]` on a terminal. Without
|
|
41
|
+
a terminal they refuse (exit 2) unless you pass `--yes`.
|
|
42
|
+
|
|
43
|
+
## Raw access
|
|
44
|
+
|
|
45
|
+
ssa api GET /api/auth/me
|
|
46
|
+
ssa api POST /api/things --data '{"a":1}'
|
|
47
|
+
ssa api PUT /api/things/1 --data @body.json
|
|
48
|
+
echo '{"a":1}' | ssa api POST /api/things --data -
|
|
49
|
+
|
|
50
|
+
Paths must be portal-relative; absolute URLs are refused so the token cannot be
|
|
51
|
+
sent to another host.
|
|
52
|
+
|
|
53
|
+
## Groups
|
|
54
|
+
|
|
55
|
+
ssa calls --mine
|
|
56
|
+
ssa call hangup 1696.3 --yes
|
|
57
|
+
ssa devices
|
|
58
|
+
|
|
59
|
+
Call control acts on real calls on the production PBX: it needs a signed-in
|
|
60
|
+
session (not an API key) and a phone extension, and always asks (or needs
|
|
61
|
+
`--yes`). Live call ids come from the portal's realtime presence feed; `ssa
|
|
62
|
+
calls` only lists calls that have ended, so its ids no longer work for
|
|
63
|
+
`hangup`/`transfer`.
|
|
64
|
+
|
|
65
|
+
ssa vpn devices
|
|
66
|
+
ssa vpn devices set 1 --location default
|
|
67
|
+
ssa vrf peers home
|
|
68
|
+
ssa vrf peer add home tablet
|
|
69
|
+
ssa vrf peer config home tablet --output tablet.conf
|
|
70
|
+
|
|
71
|
+
`vrf peer config` output contains the peer's private key: `--output` writes it
|
|
72
|
+
with mode 0600 and refuses to overwrite an existing file without `--force`.
|
|
73
|
+
Peers can be addressed by label, RouterOS name or numeric id; an ambiguous
|
|
74
|
+
label is an error that lists the candidates.
|
|
75
|
+
|
|
76
|
+
ssa sms send +66899999999 "running late"
|
|
77
|
+
ssa sms inbox --unread
|
|
78
|
+
ssa sms thread +66811111111 --follow
|
|
79
|
+
ssa sms search invoice
|
|
80
|
+
ssa sms ussd '*121#'
|
|
81
|
+
|
|
82
|
+
Use the international form (+66…) for numbers; local `0812…` numbers are not
|
|
83
|
+
normalised by the backend. `ssa sms search` needs a signed-in session, not an
|
|
84
|
+
API key. `--follow --json` emits one JSON object per line.
|
|
85
|
+
|
|
86
|
+
ssa dns zones
|
|
87
|
+
ssa dns records example.com --type TXT
|
|
88
|
+
ssa dns record add example.com www A 1.2.3.4 --proxied
|
|
89
|
+
ssa dns record set example.com <record-id> --content 9.9.9.9
|
|
90
|
+
ssa dns record rm example.com <record-id> --yes
|
|
91
|
+
|
|
92
|
+
ssa adguard instances
|
|
93
|
+
ssa adguard instances set origin --feature rewrites=apply
|
|
94
|
+
echo "$PW" | ssa adguard instances set origin --password-stdin
|
|
95
|
+
ssa adguard locations set 3 origin
|
|
96
|
+
|
|
97
|
+
`dns record set` and `adguard instances set` fetch the current object and
|
|
98
|
+
re-send every field you did not change, because the backend replaces the whole
|
|
99
|
+
object. AdGuard commands need Domain Admin; others get exit 4.
|
|
100
|
+
|
|
101
|
+
## Development
|
|
102
|
+
|
|
103
|
+
bun test # runs against a local fake portal (test/portal.ts)
|
|
104
|
+
bun run lint:fix
|
|
105
|
+
bun run typecheck
|
|
106
|
+
|
|
107
|
+
New command group: add `commands/<group>/<name>.ts` extending `AuthedCommand`
|
|
108
|
+
(or `DestructiveCommand` for deletes), implement `run(client)`, use
|
|
109
|
+
`this.call(...)` for Eden requests and `this.print(...)` for output, then
|
|
110
|
+
register it in `index.ts` and list it in `commands/root.ts`.
|