Skip to main content

​
Goal

Invoke a registered function on a running iii engine directly from the terminal, without writing application code or connecting an SDK.

​
When to Use This

  • Redriving dead-letter queue messages after fixing a bug
  • Testing a function during development without wiring up a trigger
  • Running one-off operational tasks against a live engine
  • Scripting engine operations in CI/CD pipelines or shell scripts

​
Command Reference

iii trigger \
  --function-id='<function_id>' \
  --payload='<json>'
FlagRequiredDefaultDescription
--function-idYes—The ID of the function to invoke (e.g. iii::queue::redrive, orders::process)
--payloadYes—A JSON string passed as the function’s input
--addressNolocalhostThe hostname or IP of the engine
--portNo49134The engine’s WebSocket port

​
Steps

1

Ensure the engine is running

The iii trigger command connects to a running engine instance. If you don’t have one running yet, follow the Quickstart to get started.
2

Identify the function ID

Every function registered with the engine has a unique ID. Builtin functions use the iii:: prefix. User-defined functions use the ID you specified during registration.Examples of function IDs:
  • iii::queue::redrive — builtin DLQ redrive
  • orders::process-payment — a user-defined function
  • enqueue — the builtin topic-based enqueue function
3

Build the payload

The --payload flag accepts a JSON string. This JSON becomes the function’s input — the same data it would receive if invoked via an SDK trigger() call.
# Simple object
--payload='{"queue": "payment"}'

# Nested payload
--payload='{"orderId": "ord_789", "amount": 149.99, "currency": "USD"}'

# Empty payload (for functions that don't require input)
--payload='{}'
The CLI validates that the payload is valid JSON before connecting to the engine. Invalid JSON produces an immediate error.
4

Run the command

iii trigger \
  --function-id='iii::queue::redrive' \
  --payload='{"queue": "payment"}'
The CLI connects to the engine over WebSocket, sends the invocation, and waits for the result. On success, the function’s return value is printed to stdout as pretty-printed JSON:
{
  "queue": "payment",
  "redriven": 12
}
If the function returns an error, it is printed to stderr and the process exits with code 1.

​
Targeting a Remote Engine

By default, iii trigger connects to localhost:49134. Use --address and --port to target a different engine instance: 
iii trigger \
  --function-id='iii::queue::redrive' \
  --payload='{"queue": "payment"}' \
  --address='10.0.1.5' \
  --port=49134

​
How It Works

The iii trigger command operates as a lightweight WebSocket client: The CLI connects to the engine’s WebSocket endpoint (the same protocol SDKs use), waits for the WorkerRegistered handshake, sends an InvokeFunction message with the function ID and payload, and prints the InvocationResult when it arrives.
The WebSocket protocol is documented in the Protocol reference. The iii trigger command uses the same InvokeFunction / InvocationResult message pair that all SDKs use.

​
Examples

​
Redrive a dead-letter queue

Move all failed messages from the payment queue’s DLQ back to the main queue: 
iii trigger \
  --function-id='iii::queue::redrive' \
  --payload='{"queue": "payment"}'

{
  "queue": "payment",
  "redriven": 12
}
For the full workflow of inspecting and redriving failed messages, see Use Dead Letter Queues.

​
Invoke a user-defined function

Trigger any function registered by your workers: 
iii trigger \
  --function-id='orders::process-payment' \
  --payload='{"orderId": "ord_789", "amount": 149.99, "currency": "USD"}'

​
Publish to a topic-based queue

Use the builtin enqueue function to publish a message to a topic: 
iii trigger \
  --function-id='enqueue' \
  --payload='{"topic": "order.created", "data": {"orderId": "ord_789"}}'

​
Use in a shell script

#!/bin/bash
QUEUES=("payment" "email" "notifications")

for queue in "${QUEUES[@]}"; do
  echo "Redriving $queue..."
  iii trigger \
    --function-id='iii::queue::redrive' \
    --payload="{\"queue\": \"$queue\"}"
done

​
Error Handling

ScenarioBehavior
Invalid JSON in --payloadError printed immediately, no connection attempted
Engine not running (connection refused)Error with the target address and port
Function not foundEngine returns a function_not_found error, printed to stderr
Function returns an errorError body printed to stderr, exit code 1
Connection drops before resultError indicating the connection closed unexpectedly

​
Next Steps

Trigger Actions

Compare synchronous, Void, and Enqueue invocation modes from SDKs

Dead Letter Queues

Inspect and redrive failed queue messages

Queue Module Reference

Full reference for builtin queue functions including iii::queue::redrive

Protocol Reference

WebSocket message catalog and envelope format