Docs

Documentation

Test webhooks locally like Stripe CLI

Forward production webhooks to localhost, test WebSocket connections, and trigger async requests without exposing your local server.

Overview

The ModelRiver CLI is a command-line tool for testing webhooks and WebSockets from live/production ModelRiver, similar to Stripe CLI. It allows you to:

  • Listen for webhooks via WebSocket (no public URL required)
  • Forward webhooks to localhost for development
  • Test WebSocket connections and receive real-time AI responses
  • Trigger async requests from the command line
  • Verify webhook signatures locally

Installation

From npm (Global Installation)

Bash
npm install -g @modelriver/cli

From npm (Using npx)

No installation required: run commands directly:

Bash
npx @modelriver/cli listen --print

From Source

Bash
git clone https://github.com/modelriver/modelriver-cli.git
cd modelriver-cli
npm install
npm link # Makes `modelriver` command available globally

Quick Start

Step 1: Login (One-Time Setup)

Bash
modelriver login

You'll be prompted for your API key and forward URL.

Step 2: Start Forwarding

Bash
modelriver forward

That's it! Webhooks will be forwarded to your configured URL.

Command Aliases

CommandAliasDescription
listenlListen for webhooks
forwardfForward using saved config
triggertSend async request
websocketwsTest WebSocket connection

Commands

  • Listen: Receive webhooks via WebSocket without a public URL
  • Forward: Forward webhooks to your localhost using saved config
  • Trigger: Send async AI requests from the command line
  • WebSocket: Test WebSocket connections to production

Configuration

Interactive Setup (Recommended)

Bash
modelriver login

This saves your configuration to ~/.modelriver/config.json.

Environment Variables

Bash
export MODELRIVER_API_KEY=mr_live_YOUR_API_KEY
export MODELRIVER_API_URL=https://api.modelriver.com # Optional

Config File

JSON
1{
2 "api_key": "mr_live_YOUR_API_KEY",
3 "api_url": "https://api.modelriver.com",
4 "forward_url": "http://localhost:4000/webhook/modelriver"
5}

Priority: CLI arguments > Environment variables > Config file > Defaults

Security

  • API keys are stored locally in ~/.modelriver/config.json
  • WebSocket tokens are short-lived (24 hours for CLI usage)
  • Never commit config files with API keys to version control

Next steps

  • Review Webhooks documentation for webhook integration
  • Explore Client SDK for frontend WebSocket connections
  • Check API for async request details