@modelriver/cli 1.2.5 → 2.0.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 +198 -3
- package/package.json +29 -12
- package/src/cli.js +232 -0
- package/src/commands/listen.js +17 -8
- package/src/commands/login.js +59 -16
- package/src/commands/test-webhook.js +10 -3
- package/src/commands/tool-calls.js +138 -0
- package/src/commands/tools.js +762 -0
- package/src/commands/trigger.js +8 -3
- package/src/commands/webhook.js +8 -5
- package/src/commands/websocket.js +185 -58
- package/src/index.js +2 -166
- package/src/lib/api-client.js +116 -11
- package/src/lib/cli-websocket-client.js +381 -137
- package/src/lib/config.js +141 -13
- package/src/lib/tool-forwarder.js +325 -0
- package/src/lib/tool-session-store.js +361 -0
- package/src/lib/tool-signature.js +141 -0
- package/src/lib/webhook-verifier.js +43 -16
- package/src/lib/websocket-client.js +29 -3
- package/src/utils/logger.js +8 -7
- package/src/utils/secrets.js +44 -0
- package/src/utils/tool-approvals.js +238 -0
- package/src/utils/url-helpers.js +117 -0
- package/src/utils/webhook-payload.js +9 -6
- package/tool-signature.js +3 -0
package/README.md
CHANGED
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
# ModelRiver CLI
|
|
2
2
|
|
|
3
|
-
A command-line tool for testing webhooks and
|
|
3
|
+
A command-line tool for testing webhooks, WebSockets and hosted tools from live/production ModelRiver, similar to Stripe CLI.
|
|
4
|
+
|
|
5
|
+
## Requirements
|
|
6
|
+
|
|
7
|
+
- **Node.js 22.12 or later.** Version 2.0 needs Node 22.12+ because its dependencies (chalk, ora, commander) are ESM-only and are loaded with `require()`. On older Node, stay on `@modelriver/cli@1`.
|
|
4
8
|
|
|
5
9
|
## Installation
|
|
6
10
|
|
|
@@ -73,7 +77,7 @@ modelriver t -w my-workflow -m "Hello" # Same as: modelriver trigger ...
|
|
|
73
77
|
modelriver login
|
|
74
78
|
```
|
|
75
79
|
|
|
76
|
-
This saves your configuration to `~/.modelriver/config.json`.
|
|
80
|
+
This saves your configuration to `~/.modelriver/config.json`. The file is written readable only by you (mode `0600`, folder `0700`). Set `MODELRIVER_CONFIG_DIR` to keep it in another folder.
|
|
77
81
|
|
|
78
82
|
### Environment Variables
|
|
79
83
|
|
|
@@ -84,6 +88,8 @@ export MODELRIVER_API_KEY=mr_live_YOUR_API_KEY
|
|
|
84
88
|
export MODELRIVER_API_URL=https://api.modelriver.com # Optional, defaults to production
|
|
85
89
|
```
|
|
86
90
|
|
|
91
|
+
The API URL must use `https`. Plain `http` is accepted only for `localhost`, `127.0.0.0/8` and `::1` (a local ModelRiver server).
|
|
92
|
+
|
|
87
93
|
### Config File
|
|
88
94
|
|
|
89
95
|
Create a config file at `~/.modelriver/config.json` or `.modelriverrc` in your project:
|
|
@@ -98,6 +104,24 @@ Create a config file at `~/.modelriver/config.json` or `.modelriverrc` in your p
|
|
|
98
104
|
|
|
99
105
|
**Priority**: CLI arguments > Environment variables > Config file > Defaults
|
|
100
106
|
|
|
107
|
+
A `.modelriverrc` in the current directory **cannot set `api_url`**; the CLI ignores it and prints a warning. Otherwise a repository you check out could send your API key to a server of its choosing. Set the API URL with `--api-url`, `MODELRIVER_API_URL` or `~/.modelriver/config.json`.
|
|
108
|
+
|
|
109
|
+
`modelriver tools` also **refuses an `api_key` from a `.modelriverrc`** in the current directory. A cloned repository could plant another account's key there, and that account could then send POST requests to servers on your machine. `tools` takes the key only from `--api-key`, `MODELRIVER_API_KEY` or `~/.modelriver/config.json`. For the same reason `modelriver login` never offers a `.modelriverrc` key as its default (pressing Enter would save it to `config.json`); its default comes only from `MODELRIVER_API_KEY` or `config.json`.
|
|
110
|
+
|
|
111
|
+
The API URL saved in `~/.modelriver/config.json` (for example by `modelriver login --api-url`) is used in every folder, also where a `.modelriverrc` is present.
|
|
112
|
+
|
|
113
|
+
### Command-line options
|
|
114
|
+
|
|
115
|
+
Global options (`-k/--api-key`, `--api-url`, `-p/--project-id`) go **before** the command name:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
modelriver -p proj_123 websocket --workflow my-workflow
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
After the command name, each command's own options apply, so `-p` means the port for `listen`, `forward` and `test-webhook`, and the payload for `webhook verify`. Commands that call the API also accept `-k/--api-key` and `--api-url` after the command name, and `websocket` accepts `-p/--project-id`.
|
|
122
|
+
|
|
123
|
+
The CLI never prints your API key or webhook secrets in full. It shows a masked form such as `mr_live_…a1b2`.
|
|
124
|
+
|
|
101
125
|
## Commands
|
|
102
126
|
|
|
103
127
|
### `modelriver login` - Interactive Setup
|
|
@@ -231,10 +255,19 @@ modelriver websocket --workflow my-workflow --payload '{"messages": [{"role": "u
|
|
|
231
255
|
# Connect to existing channel
|
|
232
256
|
modelriver websocket --channel-id abc-123 --project-id xyz-789
|
|
233
257
|
|
|
258
|
+
# Hosted tools: say who the request is for, and send its tool calls to `modelriver tools`
|
|
259
|
+
modelriver websocket --workflow my-workflow --message "Cancel order 1041" \
|
|
260
|
+
--end-user user_812 --cli-session cts_...
|
|
261
|
+
|
|
234
262
|
# Verbose output
|
|
235
263
|
modelriver websocket --workflow my-workflow --message "Test" --verbose
|
|
236
264
|
```
|
|
237
265
|
|
|
266
|
+
- `--end-user <id>` adds `"end_user": {"id": "<id>"}` to the request, unless `--payload` already has an `end_user`. Workflows with hosted tools need one.
|
|
267
|
+
- `--cli-session <cts_id>` adds `"tool_route": {"cli_session": "<cts_id>"}`, unless `--payload` already has a `tool_route`.
|
|
268
|
+
|
|
269
|
+
The command waits 5 minutes for the response. When a call to a tool that changes something waits for approval, it prints the call and the commands that decide it, and keeps waiting until the last waiting call expires, plus 5 minutes for the request to carry on (never more than 65 minutes per round of approvals; a later round that waits again extends it the same way). It also shows each decision. It exits with code 1 when the wait ends or the connection closes before a response, and when ModelRiver refuses the request (it then prints the error code, message and details, and for a `429` how long to wait). The WebSocket URL from the server must use `wss://` (a `ws://` URL on port 443 or a `modelriver.com` host is treated as `wss://`); only `localhost`, `127.0.0.0/8` and `::1` may use `ws://`.
|
|
270
|
+
|
|
238
271
|
**Example Output:**
|
|
239
272
|
```
|
|
240
273
|
✓ Making async request...
|
|
@@ -303,6 +336,132 @@ Channel Details
|
|
|
303
336
|
> Or use "modelriver websocket" to connect and receive responses
|
|
304
337
|
```
|
|
305
338
|
|
|
339
|
+
The secret of a webhook created with `--webhook-url` is masked. Add `--show-secret` to print it once in full.
|
|
340
|
+
|
|
341
|
+
### `modelriver tools` - Test Hosted Tools on Your Machine
|
|
342
|
+
|
|
343
|
+
With hosted tools, ModelRiver calls your workflow's tool endpoints itself. In production those must be public HTTPS URLs; ModelRiver refuses localhost and private addresses. `modelriver tools` lets you test a tool server running on your laptop: ModelRiver sends the tool calls to the CLI over its WebSocket, and the CLI forwards them to your local server.
|
|
344
|
+
|
|
345
|
+
```bash
|
|
346
|
+
modelriver tools --forward-to http://localhost:3000
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
```
|
|
350
|
+
✔ Tool forwarding active
|
|
351
|
+
|
|
352
|
+
> Session: cts_...
|
|
353
|
+
> Project: proj_...
|
|
354
|
+
> Expires: 2026-11-15T10:00:00Z
|
|
355
|
+
> Forwarding tool calls to http://localhost:3000
|
|
356
|
+
|
|
357
|
+
Add this to a POST /v1/ai/async request to send its tool calls here:
|
|
358
|
+
"tool_route": {"cli_session": "cts_..."}
|
|
359
|
+
Or send one and follow it (approvals included) from another terminal:
|
|
360
|
+
modelriver websocket -w <workflow> -m "..." --end-user <id> --cli-session cts_...
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
Then send a request that names the session:
|
|
364
|
+
|
|
365
|
+
```json
|
|
366
|
+
{
|
|
367
|
+
"workflow": "my-workflow-with-tools",
|
|
368
|
+
"messages": [{ "role": "user", "content": "What's the weather in Pune?" }],
|
|
369
|
+
"tool_route": { "cli_session": "cts_..." }
|
|
370
|
+
}
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
Each tool call is POSTed to `<forward-to origin><path of the tool's endpoint URL>`. For a tool whose endpoint is `https://tools.example.com/weather?units=metric` and `--forward-to http://localhost:3000`, the call goes to `http://localhost:3000/weather?units=metric`. The body and headers (`x-modelriver-timestamp`, `x-modelriver-tool-call-id`, `x-modelriver-key-id`, `x-modelriver-signature`) are exactly what a live call sends, so your signature check runs unchanged.
|
|
374
|
+
|
|
375
|
+
The CLI prints one line per call (tool, status, time). Add `--print` to also see each call's arguments and result.
|
|
376
|
+
|
|
377
|
+
**Options:**
|
|
378
|
+
- `--forward-to <url>` (required) - your local tool server. Only the origin is used.
|
|
379
|
+
- `--print` - print arguments and results. Calls to a tool that changes something are marked `[write]` when the server says so.
|
|
380
|
+
- `--new-session` - open a new session instead of rejoining the one saved on this machine (see "Restarting" below).
|
|
381
|
+
- `-k, --api-key <key>` - API key. Without it the key comes from `MODELRIVER_API_KEY` or `~/.modelriver/config.json`, never from a `.modelriverrc` in the current directory.
|
|
382
|
+
- `--api-url <url>` - API base URL
|
|
383
|
+
- `-v, --verbose` - verbose output
|
|
384
|
+
|
|
385
|
+
**Safety rules:**
|
|
386
|
+
- Calls are only forwarded to this machine. The host must be `localhost` or resolve only to `127.0.0.0/8` or `::1`. The CLI checks the resolved address for every call and connects to that checked address. Anything else is refused, and ModelRiver gets a `target_refused` error.
|
|
387
|
+
- `http` and `https` are both allowed. Redirects are not followed.
|
|
388
|
+
- The CLI waits no longer than the tool's timeout, and stops reading a response once it is larger than the tool's result size limit (`too_large`).
|
|
389
|
+
- A request only goes to the CLI when it names the session in `tool_route`. If the CLI is not connected, the request is refused; ModelRiver never falls back to the tool's real URL.
|
|
390
|
+
- If the CLI disconnects or stops during a run, new tool calls fail at once as tool unavailable. Only calls already sent to the CLI wait, and time out if no result comes back. On Ctrl+C the CLI answers its in-flight calls with `connection_failed` before it exits; a call that arrives after Ctrl+C is not forwarded and is answered `target_refused`, so ModelRiver records it as not sent.
|
|
391
|
+
- The session lasts 24 hours. Treat the session ID like a password while it is valid. When it reaches its expiry time, the CLI says the session expired and exits with code 1; start `modelriver tools` again for a new session ID. If the WebSocket drops, the CLI reconnects with a new token and rejoins the same session. A result that was ready while the CLI was disconnected is sent after the rejoin, as long as the call's timeout hasn't passed, and ModelRiver takes it if the call is still waiting. ModelRiver uses the first result it gets for a call; a later copy (the CLI may have sent one just before the connection dropped) is answered `already_answered` and changes nothing. If the call stopped waiting first, the CLI notes that ModelRiver is no longer waiting for it, and the call is recorded as timed out (as unknown, for a tool that changes something). The CLI never forwards a call to your server twice.
|
|
392
|
+
- **Restarting.** The session is saved in `~/.modelriver/tool-sessions.json` (readable only by you: `0600`, in a `0700` folder). Start `modelriver tools` again with the same API key, API URL and `--forward-to` origin, also after it was killed, and it rejoins that session instead of opening a new one, as long as the session has at least an hour left. With less than an hour left it opens a new one (with a new ID), so a restarted CLI never runs on a session about to end. Requests that already name the session keep working, and a call that was waiting for approval reaches the restarted CLI once it is approved. The session ID is printed in full only when the session is opened; after a restart it is shown as `cts_…1234`. If the saved session can no longer be joined (it expired or was removed), the CLI says so and opens a new one, with a new ID. If hosted tools is off for the organization, it stops with that message and keeps the saved session for later. `--new-session` always opens a new one. Several CLIs can start and stop at the same time: every change to the file is made under a lock (`tool-sessions.json.lock`; a lock left by a CLI that crashed is taken over at once, or after 5 seconds when it came from another machine sharing the folder), and a CLI only removes its own session's record, never a newer one another CLI saved. If the file or its folder is readable by others when it is read, the CLI tightens it back to `0600`/`0700`.
|
|
393
|
+
- **Never twice, across restarts too.** The file also lists the calls the CLI has handed to your server (the latest 1000 per session), written before each call goes out. A restarted CLI answers any of them `connection_failed` without forwarding it. ModelRiver itself never sends a call again: a call that was in flight when the CLI was killed is not re-sent after the restart. It times out, and for a tool that changes something its outcome is recorded as unknown.
|
|
394
|
+
- One connection per session. Starting a second `modelriver tools` with the same API key and `--forward-to` rejoins the same session, so it takes over from the first. If another connection joins the same session, it takes over: ModelRiver sends the tool calls there, and this CLI stops and says so instead of reconnecting.
|
|
395
|
+
- The WebSocket URL the server gives must use `wss://`. Only `localhost`, `127.0.0.0/8` and `::1` may use `ws://`.
|
|
396
|
+
- Each API key owner can have up to 5 connected tool sessions per project. Opening another one replaces your oldest disconnected session; if all 5 are connected, it is refused until you stop one.
|
|
397
|
+
- Response bodies must be UTF-8. For any other body the CLI sends the status code without the body.
|
|
398
|
+
|
|
399
|
+
**Protect your production endpoints:** the CLI session receives each tool call exactly as signed, so a valid signature alone doesn't prove a call came from a live run. Calls meant for the CLI have `request.via == "cli"` in their body. Production tool endpoints should reject those.
|
|
400
|
+
|
|
401
|
+
Errors the CLI can send back for a call: `timeout`, `connection_failed`, `too_large`, `target_refused`.
|
|
402
|
+
|
|
403
|
+
#### Tools that change something
|
|
404
|
+
|
|
405
|
+
A tool marked as changing something (refund an order, send an email) never runs on the model's say-so alone. ModelRiver pauses the request and asks the request's end user first. Only an approved call is sent to `modelriver tools`, and it is sent once.
|
|
406
|
+
|
|
407
|
+
1. Start `modelriver tools` and leave it running.
|
|
408
|
+
2. In another terminal, send a request that names the session and an end user, and follow it:
|
|
409
|
+
|
|
410
|
+
```bash
|
|
411
|
+
modelriver websocket -w my-workflow -m "Cancel order 1041" --end-user user_812 --cli-session cts_...
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
3. When the model calls the tool, the request waits. `modelriver websocket` shows what the end user would see, and the commands that decide it:
|
|
415
|
+
|
|
416
|
+
```
|
|
417
|
+
⚠ Waiting for approval: cancel_order (call tc_3f2a9c1d5b7e4a6f8c0d1e2b)
|
|
418
|
+
Prompt: Cancel this order? This can't be undone.
|
|
419
|
+
Arguments shown to the end user:
|
|
420
|
+
order_id: 1041
|
|
421
|
+
Expires: 2026-11-14T10:20:00Z
|
|
422
|
+
Decide it with:
|
|
423
|
+
modelriver tools approve tc_3f2a9c1d5b7e4a6f8c0d1e2b --end-user user_812
|
|
424
|
+
modelriver tools reject tc_3f2a9c1d5b7e4a6f8c0d1e2b --end-user user_812
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
4. Approve or decline it, as your backend would for its user:
|
|
428
|
+
|
|
429
|
+
```bash
|
|
430
|
+
modelriver tools approve tc_3f2a9c1d5b7e4a6f8c0d1e2b --end-user user_812
|
|
431
|
+
modelriver tools reject tc_3f2a9c1d5b7e4a6f8c0d1e2b --end-user user_812 # or: decline
|
|
432
|
+
modelriver tools show tc_3f2a9c1d5b7e4a6f8c0d1e2b # prompt and shown arguments
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
These call `POST /v1/ai/tool-calls/:call_id/approve` (or `/reject`) with `{"end_user": {"id": "..."}}`, and `GET /v1/ai/tool-calls/:call_id`, with your API key. `--end-user` must be the `end_user.id` the request was sent with. Prompts and arguments are printed as plain text: control characters, and invisible or direction-changing characters (zero-width characters, bidi embeddings, overrides and isolates such as U+202E, U+FEFF), show as `\uXXXX`, so text from the model can't drive your terminal or make an approval read differently from what it says.
|
|
436
|
+
|
|
437
|
+
What to expect:
|
|
438
|
+
- **Keep `modelriver tools` running while a call waits.** The wait lasts as long as the workflow's approval timeout (10 minutes by default, at most an hour). If the CLI isn't connected when the call is approved, the call is not sent, and ModelRiver records it as not run (`tool_unavailable`). It never falls back to the tool's real URL.
|
|
439
|
+
- **Once, never retried.** An approved call reaches your server at most once. ModelRiver never retries a tool that changes something, and the CLI remembers every call of the session: a repeated `tool_call` (same `reply_ref` or same call id) is never forwarded again; a repeat under a new `reply_ref` is answered `connection_failed`.
|
|
440
|
+
- **Unknown outcomes.** If the call may have reached your server but no answer says what happened (a timeout, a dropped connection, a `5xx`, a response larger than the result size limit, or Ctrl+C), ModelRiver records the outcome as unknown and tells the model not to claim it succeeded. A `4xx` stays an error: your tool refused the call. A `2xx` whose body isn't a JSON object or array counts as done: the call is recorded as `ok`, and the model is told the action ran but its result could not be read.
|
|
441
|
+
- **Ctrl+C mid-call.** The CLI aborts its request to your server and answers `connection_failed`. Your server may already have done the work, so the CLI warns that the call may have run, and ModelRiver records it as unknown.
|
|
442
|
+
- **Timeouts and takeovers.** When your server doesn't answer within the tool's timeout, or another connection takes over the session mid-call, the CLI stops waiting and warns that the call may already have run.
|
|
443
|
+
- **Declined or expired calls** are not run. The model is told, and the request carries on.
|
|
444
|
+
- **Errors from approve/reject:** `end_user_required` / `end_user_invalid` (pass `--end-user`), `tool_call_not_found` (wrong id, another project's call, a Playground call, or a call that needed no approval), `end_user_mismatch` (another end user's call), `tool_call_already_decided` (with the decision it already has), `tool_approval_expired`, and `429` with the number of seconds to wait. Repeating the same decision is fine.
|
|
445
|
+
|
|
446
|
+
#### Check the tool signature
|
|
447
|
+
|
|
448
|
+
Your tool server should check `x-modelriver-signature` on every call. The CLI includes a checker you can use from Node:
|
|
449
|
+
|
|
450
|
+
```js
|
|
451
|
+
const ToolSignature = require('@modelriver/cli/tool-signature');
|
|
452
|
+
|
|
453
|
+
app.post('/tools/cancel-order', express.raw({ type: 'application/json' }), (req, res) => {
|
|
454
|
+
// req.body is the raw body (a Buffer): check it before parsing
|
|
455
|
+
if (!ToolSignature.verifyRequest(req.headers, req.body, process.env.MODELRIVER_TOOL_SECRET)) {
|
|
456
|
+
return res.status(401).json({ error: { message: 'Bad signature' } });
|
|
457
|
+
}
|
|
458
|
+
const call = JSON.parse(req.body);
|
|
459
|
+
// ...
|
|
460
|
+
});
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
It checks `v2=hex(HMAC-SHA256(secret, "v2.<timestamp>.<call id>.<raw body>"))` against every value in the header (there are two, comma-separated, while a secret is being rotated), and rejects a timestamp more than 300 seconds from now. Pass an array of secrets to accept an old and a new one. Use the raw body: parsing the JSON and encoding it again changes the bytes. `ToolSignature.check(...)` reports the signature and the timestamp separately. This is not the webhook signature; `modelriver webhook verify` checks webhooks only.
|
|
464
|
+
|
|
306
465
|
### `modelriver test-webhook` - Test Webhook Delivery End-to-End
|
|
307
466
|
|
|
308
467
|
Test the complete webhook flow - creates a webhook, makes an async request, and waits for the webhook response:
|
|
@@ -436,6 +595,7 @@ The CLI connects to ModelRiver WebSockets using the Phoenix protocol:
|
|
|
436
595
|
1. Connect to `wss://api.modelriver.com/socket?token={ws_token}`
|
|
437
596
|
2. Join channel: `ai_response:{project_id}:{channel_id}`
|
|
438
597
|
3. Listen for `response` event containing the AI response
|
|
598
|
+
4. For hosted tools, also `tool_state` (sent on join), `tool_approval_required` and `tool_approval_resolved`
|
|
439
599
|
|
|
440
600
|
## Troubleshooting
|
|
441
601
|
|
|
@@ -453,10 +613,22 @@ Set the API key via:
|
|
|
453
613
|
- Check network connectivity
|
|
454
614
|
- If using production, ensure you're using `wss://` (secure WebSocket)
|
|
455
615
|
|
|
616
|
+
### "tools: ... is not loopback"
|
|
617
|
+
|
|
618
|
+
`modelriver tools` only forwards to this machine. Use `http://localhost:<port>`, `http://127.0.0.1:<port>` or `http://[::1]:<port>`. If your tool server runs in a container or VM, publish its port on localhost.
|
|
619
|
+
|
|
620
|
+
### "Refusing WebSocket URL ...: it must use wss"
|
|
621
|
+
|
|
622
|
+
The server gave a WebSocket URL with plain `ws://` for a host other than this machine. The CLI refuses it so its token and your tool calls are never sent unencrypted. Check `--api-url`; a local ModelRiver server on `localhost` may use `ws://`.
|
|
623
|
+
|
|
624
|
+
### "API URL must use https"
|
|
625
|
+
|
|
626
|
+
Use an `https://` API URL. Only `localhost`, `127.0.0.0/8` and `::1` may use `http://`.
|
|
627
|
+
|
|
456
628
|
### "Webhook signature verification failed"
|
|
457
629
|
|
|
458
630
|
- Ensure the secret matches exactly (no extra spaces)
|
|
459
|
-
- Verify timestamp is recent (within 5 minutes)
|
|
631
|
+
- Verify timestamp is recent (within 5 minutes). The CLI rejects signatures whose timestamp is more than 5 minutes from now, as a receiver should; `modelriver webhook verify` says so when only the timestamp is the problem
|
|
460
632
|
- Check that payload structure matches expected format
|
|
461
633
|
|
|
462
634
|
**Note**: The CLI does not support creating permanent webhooks. Use the ModelRiver dashboard to create webhooks for production use. The CLI only creates temporary webhooks for testing (via `listen` and `test-webhook` commands), which are automatically cleaned up.
|
|
@@ -472,6 +644,9 @@ The CLI uses these ModelRiver API endpoints:
|
|
|
472
644
|
- `POST /v1/webhooks` - Create a new webhook
|
|
473
645
|
- `DELETE /v1/webhooks/:id` - Delete a webhook
|
|
474
646
|
- `POST /v1/cli/connect` - Connect CLI and get WebSocket token
|
|
647
|
+
- `POST /v1/cli/tool-sessions` - Open a CLI tool session (`modelriver tools`)
|
|
648
|
+
- `GET /v1/ai/tool-calls/:call_id` - Show a call waiting for approval (`modelriver tools show`)
|
|
649
|
+
- `POST /v1/ai/tool-calls/:call_id/approve` and `/reject` - Decide it (`modelriver tools approve|reject`)
|
|
475
650
|
- `POST /v1/callback/:channel_id` - Complete event-driven callback
|
|
476
651
|
|
|
477
652
|
**Development** (localhost or custom API URL):
|
|
@@ -479,6 +654,16 @@ The CLI uses these ModelRiver API endpoints:
|
|
|
479
654
|
|
|
480
655
|
## Development
|
|
481
656
|
|
|
657
|
+
### Pointing the CLI at a local ModelRiver server
|
|
658
|
+
|
|
659
|
+
For working on ModelRiver itself: save your local server's URL once, and every command uses it.
|
|
660
|
+
|
|
661
|
+
```bash
|
|
662
|
+
modelriver login --api-url http://localhost:4000
|
|
663
|
+
```
|
|
664
|
+
|
|
665
|
+
`--api-url` isn't listed in `modelriver login --help`. Only https URLs, or http to localhost, 127.0.0.0/8 or ::1, are accepted. `MODELRIVER_API_URL` or `--api-url` on a command still override the saved URL. The saved URL applies in every folder, including ones with a `.modelriverrc`. To go back to production, run `modelriver login --api-url https://api.modelriver.com`.
|
|
666
|
+
|
|
482
667
|
### Running Tests
|
|
483
668
|
|
|
484
669
|
The CLI includes a Jest test suite. To run the tests:
|
|
@@ -493,6 +678,16 @@ Tests cover critical components including:
|
|
|
493
678
|
- API client validation
|
|
494
679
|
- Output formatting
|
|
495
680
|
- Event-driven webhook payload helpers
|
|
681
|
+
- Tool forwarding: loopback-only targets (including names that resolve to public IPs), exact body and headers, timeouts and size limits, Ctrl+C aborting the local request
|
|
682
|
+
- Tool approvals: approve/reject/show requests and error messages, following a paused request, plain-text output
|
|
683
|
+
- The v2 tool signature, against the documented test value
|
|
684
|
+
- WebSocket client: push/reply refs, several topics, reconnect with a fresh token
|
|
685
|
+
- Config file permissions and the `.modelriverrc` `api_url` rule
|
|
686
|
+
- `modelriver login`: what it asks, the saved `--api-url`, and the Quick Start
|
|
687
|
+
|
|
688
|
+
The tests never touch your real `~/.modelriver`: `test/support/isolate-home.js` points `MODELRIVER_CONFIG_DIR` and `HOME` at a temp folder for every test file, makes `os.homedir()` throw, fails any file access inside the real `~/.modelriver`, and gives child processes the tests start (without their own `env`) that temp environment too.
|
|
689
|
+
|
|
690
|
+
Tests run on Node 22.12+. chalk and ora are ESM-only, and Jest can only `require()` ESM on Node 24.9+, so the tests map them to small stand-ins in `test/support/`.
|
|
496
691
|
|
|
497
692
|
|
|
498
693
|
## License
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@modelriver/cli",
|
|
3
|
-
"version": "
|
|
4
|
-
"description": "ModelRiver CLI for testing webhooks and
|
|
3
|
+
"version": "2.0.0",
|
|
4
|
+
"description": "ModelRiver CLI for testing webhooks, WebSockets and hosted tools from production",
|
|
5
5
|
"main": "src/index.js",
|
|
6
6
|
"bin": {
|
|
7
7
|
"modelriver": "bin/modelriver"
|
|
@@ -18,7 +18,9 @@
|
|
|
18
18
|
"testing",
|
|
19
19
|
"ai",
|
|
20
20
|
"llm",
|
|
21
|
-
"api"
|
|
21
|
+
"api",
|
|
22
|
+
"tools",
|
|
23
|
+
"tool-calling"
|
|
22
24
|
],
|
|
23
25
|
"author": "ModelRiver",
|
|
24
26
|
"license": "MIT",
|
|
@@ -31,24 +33,39 @@
|
|
|
31
33
|
"url": "https://github.com/modelriver/modelriver-cli/issues"
|
|
32
34
|
},
|
|
33
35
|
"dependencies": {
|
|
34
|
-
"axios": "^1.
|
|
35
|
-
"chalk": "^
|
|
36
|
-
"commander": "^
|
|
37
|
-
"express": "^
|
|
38
|
-
"ora": "^
|
|
39
|
-
"ws": "^8.
|
|
36
|
+
"axios": "^1.21.1",
|
|
37
|
+
"chalk": "^6.0.1",
|
|
38
|
+
"commander": "^15.1.0",
|
|
39
|
+
"express": "^5.3.0",
|
|
40
|
+
"ora": "^10.0.0",
|
|
41
|
+
"ws": "^8.23.0"
|
|
40
42
|
},
|
|
41
43
|
"devDependencies": {
|
|
42
|
-
"jest": "^
|
|
44
|
+
"jest": "^30.5.2"
|
|
43
45
|
},
|
|
44
46
|
"engines": {
|
|
45
|
-
"node": ">=
|
|
47
|
+
"node": ">=22.12"
|
|
46
48
|
},
|
|
47
49
|
"files": [
|
|
48
50
|
"bin/",
|
|
49
51
|
"src/",
|
|
52
|
+
"tool-signature.js",
|
|
50
53
|
"README.md",
|
|
51
54
|
"!src/**/*.test.js",
|
|
52
55
|
"!**/*.test.js"
|
|
53
|
-
]
|
|
56
|
+
],
|
|
57
|
+
"jest": {
|
|
58
|
+
"testEnvironment": "node",
|
|
59
|
+
"moduleNameMapper": {
|
|
60
|
+
"^chalk$": "<rootDir>/test/support/chalk.js",
|
|
61
|
+
"^ora$": "<rootDir>/test/support/ora.js"
|
|
62
|
+
},
|
|
63
|
+
"testPathIgnorePatterns": [
|
|
64
|
+
"/node_modules/",
|
|
65
|
+
"/test/support/"
|
|
66
|
+
],
|
|
67
|
+
"setupFilesAfterEnv": [
|
|
68
|
+
"<rootDir>/test/support/isolate-home.js"
|
|
69
|
+
]
|
|
70
|
+
}
|
|
54
71
|
}
|
package/src/cli.js
ADDED
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
const { Command, Option } = require('commander');
|
|
2
|
+
const config = require('./lib/config');
|
|
3
|
+
const { version } = require('../package.json');
|
|
4
|
+
|
|
5
|
+
function defaultActions() {
|
|
6
|
+
return {
|
|
7
|
+
login: (...args) => require('./commands/login').loginCommand(...args),
|
|
8
|
+
listen: (...args) => require('./commands/listen').listenCommand(...args),
|
|
9
|
+
forward: (...args) => require('./commands/forward').forwardCommand(...args),
|
|
10
|
+
websocket: (...args) => require('./commands/websocket').websocketCommand(...args),
|
|
11
|
+
callback: (...args) => require('./commands/callback').callbackCommand(...args),
|
|
12
|
+
testWebhook: (...args) => require('./commands/test-webhook').testWebhookCommand(...args),
|
|
13
|
+
trigger: (...args) => require('./commands/trigger').triggerCommand(...args),
|
|
14
|
+
tools: (...args) => require('./commands/tools').toolsCommand(...args),
|
|
15
|
+
toolsShow: (...args) => require('./commands/tool-calls').showToolCallCommand(...args),
|
|
16
|
+
toolsApprove: (options) => require('./commands/tool-calls').decideToolCallCommand('approve', options),
|
|
17
|
+
toolsReject: (options) => require('./commands/tool-calls').decideToolCallCommand('reject', options),
|
|
18
|
+
listWebhooks: (...args) => require('./commands/webhook').listWebhooks(...args),
|
|
19
|
+
verifyWebhook: (...args) => require('./commands/webhook').verifyWebhook(...args),
|
|
20
|
+
};
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Add the API options to a command that talks to ModelRiver, so they work
|
|
25
|
+
* after the command name too (`modelriver tools -k ...`).
|
|
26
|
+
*/
|
|
27
|
+
function withApiOptions(command) {
|
|
28
|
+
return command
|
|
29
|
+
.option('-k, --api-key <key>', 'ModelRiver API key (or set MODELRIVER_API_KEY)')
|
|
30
|
+
.option('--api-url <url>', 'API base URL (default: https://api.modelriver.com)');
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Build the CLI.
|
|
35
|
+
*
|
|
36
|
+
* Global options go before the command name (`modelriver -k KEY listen`), so
|
|
37
|
+
* each command owns its own short options: `-p` is the port for listen,
|
|
38
|
+
* forward and test-webhook, and the payload for `webhook verify`.
|
|
39
|
+
*
|
|
40
|
+
* @param {object} [actions] - command handlers (tests pass mocks)
|
|
41
|
+
* @returns {Command}
|
|
42
|
+
*/
|
|
43
|
+
function createProgram(actions = defaultActions()) {
|
|
44
|
+
const program = new Command();
|
|
45
|
+
|
|
46
|
+
program
|
|
47
|
+
.name('modelriver')
|
|
48
|
+
.description('ModelRiver CLI for testing webhooks, WebSockets and hosted tools from production')
|
|
49
|
+
.version(version)
|
|
50
|
+
.enablePositionalOptions();
|
|
51
|
+
|
|
52
|
+
// Global options
|
|
53
|
+
program
|
|
54
|
+
.option('-k, --api-key <key>', 'ModelRiver API key (or set MODELRIVER_API_KEY)')
|
|
55
|
+
.option('--api-url <url>', 'API base URL (default: https://api.modelriver.com)')
|
|
56
|
+
.option('-p, --project-id <id>', 'Project ID (or set MODELRIVER_PROJECT_ID)');
|
|
57
|
+
|
|
58
|
+
const api = (options) => ({
|
|
59
|
+
apiKey: options.apiKey || program.opts().apiKey,
|
|
60
|
+
apiUrl: options.apiUrl || program.opts().apiUrl || config.getApiUrl(),
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
// Login command - interactive setup
|
|
64
|
+
program
|
|
65
|
+
.command('login')
|
|
66
|
+
.description('Configure your ModelRiver API key and forward URL interactively')
|
|
67
|
+
// For ModelRiver's own developers: save a local server's URL. Not listed.
|
|
68
|
+
.addOption(new Option('--api-url <url>').hideHelp())
|
|
69
|
+
.action((options) => actions.login({ ...options, apiUrl: options.apiUrl || program.opts().apiUrl }));
|
|
70
|
+
|
|
71
|
+
// Listen command with alias 'l'
|
|
72
|
+
withApiOptions(program
|
|
73
|
+
.command('listen')
|
|
74
|
+
.alias('l')
|
|
75
|
+
.description('Forward webhooks from production to local server via WebSocket'))
|
|
76
|
+
.option('-p, --port <port>', 'Local server port (default: 3001)')
|
|
77
|
+
.option('-f, --forward', 'Forward to external server (do not start internal server)')
|
|
78
|
+
.option('--print', 'Print webhook payloads to console')
|
|
79
|
+
.option('-v, --verbose', 'Verbose output')
|
|
80
|
+
.action((options) => actions.listen({ ...options, ...api(options) }));
|
|
81
|
+
|
|
82
|
+
// Forward command with alias 'f' - simplified webhook forwarding
|
|
83
|
+
program
|
|
84
|
+
.command('forward')
|
|
85
|
+
.alias('f')
|
|
86
|
+
.description('Forward webhooks using saved configuration (shortcut for listen --forward --print)')
|
|
87
|
+
.option('-p, --port <port>', 'Override target port')
|
|
88
|
+
.option('-v, --verbose', 'Verbose output')
|
|
89
|
+
.action((options) => actions.forward(options));
|
|
90
|
+
|
|
91
|
+
// WebSocket command with alias 'ws'
|
|
92
|
+
withApiOptions(program
|
|
93
|
+
.command('websocket')
|
|
94
|
+
.alias('ws')
|
|
95
|
+
.description('Test WebSocket connection to production'))
|
|
96
|
+
.option('-p, --project-id <id>', 'Project ID (or set MODELRIVER_PROJECT_ID)')
|
|
97
|
+
.option('-w, --workflow <name>', 'Workflow name')
|
|
98
|
+
.option('-m, --message <text>', 'Test message')
|
|
99
|
+
.option('-P, --payload <json>', 'Custom JSON payload')
|
|
100
|
+
.option('-c, --channel-id <id>', 'Existing channel ID (requires --project-id)')
|
|
101
|
+
.option('--end-user <id>', 'Send end_user {"id": <id>} with the request (hosted tools), and use it in the approve/reject commands shown')
|
|
102
|
+
.option('--cli-session <cts_id>', 'Send the request\'s tool calls to a "modelriver tools" session (tool_route)')
|
|
103
|
+
.option('-v, --verbose', 'Verbose output')
|
|
104
|
+
.action((options) => actions.websocket({
|
|
105
|
+
...options,
|
|
106
|
+
...api(options),
|
|
107
|
+
projectId: options.projectId || program.opts().projectId,
|
|
108
|
+
}));
|
|
109
|
+
|
|
110
|
+
// Callback command - complete event-driven flows
|
|
111
|
+
withApiOptions(program
|
|
112
|
+
.command('callback')
|
|
113
|
+
.description('Send an event-driven callback to complete a pending channel'))
|
|
114
|
+
.option('-c, --channel-id <id>', 'Channel ID from trigger/listen output')
|
|
115
|
+
.option('--callback-url <url>', 'Full callback URL from webhook payload')
|
|
116
|
+
.option('-d, --data <json>', 'Callback data object JSON')
|
|
117
|
+
.option('-P, --payload <json>', 'Full callback payload JSON')
|
|
118
|
+
.option('--task-id <id>', 'Optional task ID')
|
|
119
|
+
.option('--metadata <json>', 'Optional metadata object JSON')
|
|
120
|
+
.action((options) => actions.callback({ ...options, ...api(options) }));
|
|
121
|
+
|
|
122
|
+
// Test Webhook command
|
|
123
|
+
withApiOptions(program
|
|
124
|
+
.command('test-webhook')
|
|
125
|
+
.description('Test webhook delivery - creates webhook, makes request, waits for response'))
|
|
126
|
+
.option('-w, --workflow <name>', 'Workflow name')
|
|
127
|
+
.option('-m, --message <text>', 'Test message')
|
|
128
|
+
.option('-P, --payload <json>', 'Custom JSON payload')
|
|
129
|
+
.option('-u, --webhook-url <url>', 'Webhook URL (if not provided, starts local server on --port)')
|
|
130
|
+
.option('-s, --secret <secret>', 'Webhook secret (optional, auto-generated if not provided)')
|
|
131
|
+
.option('--show-secret', 'Print the new webhook secret in full (hidden by default)')
|
|
132
|
+
.option('-p, --port <port>', 'Local server port when using local server (default: 3001)')
|
|
133
|
+
.option('-v, --verbose', 'Verbose output')
|
|
134
|
+
.action((options) => actions.testWebhook({ ...options, ...api(options) }));
|
|
135
|
+
|
|
136
|
+
// Trigger command with alias 't'
|
|
137
|
+
withApiOptions(program
|
|
138
|
+
.command('trigger')
|
|
139
|
+
.alias('t')
|
|
140
|
+
.description('Send test async request'))
|
|
141
|
+
.option('-w, --workflow <name>', 'Workflow name')
|
|
142
|
+
.option('-m, --message <text>', 'Test message')
|
|
143
|
+
.option('-P, --payload <json>', 'Custom JSON payload')
|
|
144
|
+
.option('-u, --webhook-url <url>', 'Webhook URL to receive response')
|
|
145
|
+
.option('--print-channel', 'Print channel details')
|
|
146
|
+
.option('--show-secret', 'Print the new webhook secret in full (hidden by default)')
|
|
147
|
+
.action((options) => actions.trigger({ ...options, ...api(options) }));
|
|
148
|
+
|
|
149
|
+
// Tools command - send hosted tool calls to a server on this machine
|
|
150
|
+
const toolsCmd = withApiOptions(program
|
|
151
|
+
.command('tools')
|
|
152
|
+
.description('Forward hosted tool calls to a tool server on this machine (localhost only)'))
|
|
153
|
+
// Checked in the action rather than with requiredOption, which commander
|
|
154
|
+
// would also demand from `tools show|approve|reject`.
|
|
155
|
+
.option('--forward-to <url>', 'Local tool server origin, e.g. http://localhost:3000 (localhost, 127.0.0.0/8 or ::1)')
|
|
156
|
+
.option('--print', 'Print each call\'s arguments and result')
|
|
157
|
+
.option('--new-session', 'Open a new session instead of rejoining the one saved on this machine')
|
|
158
|
+
.option('-v, --verbose', 'Verbose output')
|
|
159
|
+
.addHelpText('after', `
|
|
160
|
+
Opens a CLI tool session and prints its ID. Send a request with
|
|
161
|
+
"tool_route": {"cli_session": "<session id>"}
|
|
162
|
+
and ModelRiver sends that request's tool calls here. Each call is POSTed to
|
|
163
|
+
<forward-to origin><path of the tool's endpoint URL> with the same body and
|
|
164
|
+
signature headers a live call has, so your signature check runs unchanged.
|
|
165
|
+
|
|
166
|
+
Stopped or restarted? Start it again with the same API key and --forward-to:
|
|
167
|
+
it rejoins the same session (saved, readable only by you, in the config
|
|
168
|
+
folder), so requests that name it keep working. --new-session opens a new one.
|
|
169
|
+
|
|
170
|
+
A call to a tool that changes something arrives only after its end user
|
|
171
|
+
approves it. Keep this running while it waits; decide it with
|
|
172
|
+
modelriver tools approve <call_id> --end-user <id>
|
|
173
|
+
modelriver tools reject <call_id> --end-user <id>
|
|
174
|
+
|
|
175
|
+
The API key comes from --api-key, MODELRIVER_API_KEY or ~/.modelriver/config.json,
|
|
176
|
+
never from a .modelriverrc in the current directory.`)
|
|
177
|
+
.action((options, command) => {
|
|
178
|
+
if (!options.forwardTo) {
|
|
179
|
+
command.error("error: required option '--forward-to <url>' not specified");
|
|
180
|
+
}
|
|
181
|
+
return actions.tools({ ...options, ...api(options) });
|
|
182
|
+
});
|
|
183
|
+
|
|
184
|
+
// Options given before the subcommand name (`tools -k KEY approve ...`)
|
|
185
|
+
// belong to `tools`; use them when the subcommand has none.
|
|
186
|
+
const toolsApi = (options) => api({
|
|
187
|
+
apiKey: options.apiKey || toolsCmd.opts().apiKey,
|
|
188
|
+
apiUrl: options.apiUrl || toolsCmd.opts().apiUrl,
|
|
189
|
+
});
|
|
190
|
+
|
|
191
|
+
withApiOptions(toolsCmd
|
|
192
|
+
.command('show <call_id>')
|
|
193
|
+
.description('Show a call waiting for approval: its prompt and the arguments the end user sees'))
|
|
194
|
+
.action((callId, options) => actions.toolsShow({ ...options, ...toolsApi(options), callId }));
|
|
195
|
+
|
|
196
|
+
withApiOptions(toolsCmd
|
|
197
|
+
.command('approve <call_id>')
|
|
198
|
+
.description('Approve a call waiting for approval, as the end user (sent the way your backend would)'))
|
|
199
|
+
.requiredOption('--end-user <id>', 'The end_user.id the request was sent with')
|
|
200
|
+
.action((callId, options) => actions.toolsApprove({ ...options, ...toolsApi(options), callId }));
|
|
201
|
+
|
|
202
|
+
withApiOptions(toolsCmd
|
|
203
|
+
.command('reject <call_id>')
|
|
204
|
+
.alias('decline')
|
|
205
|
+
.description('Decline a call waiting for approval, as the end user; it will not run'))
|
|
206
|
+
.requiredOption('--end-user <id>', 'The end_user.id the request was sent with')
|
|
207
|
+
.action((callId, options) => actions.toolsReject({ ...options, ...toolsApi(options), callId }));
|
|
208
|
+
|
|
209
|
+
// Webhook commands
|
|
210
|
+
const webhookCmd = program
|
|
211
|
+
.command('webhook')
|
|
212
|
+
.description('Webhook management commands (read-only and verification)');
|
|
213
|
+
|
|
214
|
+
withApiOptions(webhookCmd
|
|
215
|
+
.command('list')
|
|
216
|
+
.description('List all webhooks'))
|
|
217
|
+
.option('-v, --verbose', 'Show detailed information')
|
|
218
|
+
.action((options) => actions.listWebhooks({ ...options, ...api(options) }));
|
|
219
|
+
|
|
220
|
+
webhookCmd
|
|
221
|
+
.command('verify')
|
|
222
|
+
.description('Verify webhook signature')
|
|
223
|
+
.requiredOption('-p, --payload <file|json>', 'Payload file path or JSON string')
|
|
224
|
+
.requiredOption('-s, --signature <sig>', 'X-ModelRiver-Signature header value')
|
|
225
|
+
.requiredOption('-t, --timestamp <ts>', 'X-ModelRiver-Timestamp header value')
|
|
226
|
+
.requiredOption('--secret <secret>', 'Webhook secret')
|
|
227
|
+
.action((options, command) => actions.verifyWebhook(options, command));
|
|
228
|
+
|
|
229
|
+
return program;
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
module.exports = { createProgram };
|