CLI reference

ricochet receives webhooks on your machine, replays stored events and sends sample events. Install it as in the quickstart; ricochet --help and ricochet <command> --help print the same reference.

Global options

These work with every command.

Option	Environment variable	Meaning
--project <PROJECT>	RICOCHET_PROJECT	The project, by ID or name; needed when you have more than one.
--env <ENVIRONMENT>	RICOCHET_ENV	dev (the default), staging or production.
--color <WHEN>	NO_COLOR	auto (the default: colour on a terminal, unless NO_COLOR is set), always or never.
--server <SERVER>	RICOCHET_SERVER	The Ricochet server, https://getricochet.dev by default.
-h, --help		Print help.
-V, --version		Print the version.

ricochet login

Signs in in the browser. The CLI shows a code and opens the dashboard, where you confirm it; the CLI then stores a token, valid for 90 days, in the operating system’s keychain (macOS Keychain, Windows Credential Manager, Secret Service on Linux), or in an owner-only file when there is no keychain.

Option	Meaning
--no-browser	Print the link instead of opening a browser, for SSH sessions.

ricochet logout signs out on this machine and revokes the token. ricochet whoami shows who you are signed in as.

ricochet listen

Forwards events to a local server.

ricochet listen --forward localhost:3000/webhooks
ricochet listen --forward 3000,source=stripe --forward 4000,source=github
ricochet listen

With --forward (signed in), the CLI uses your own CLI destination in the environment, creating it if needed, and connects it to the environment’s sources (or only those given with --source). Each event is forwarded to every target that takes it, and the first matching target’s answer is recorded as the delivery’s attempt. The targets, the project and the environment are saved in .ricochet.json in the working directory, so a bare ricochet listen there (or in a subdirectory) restores them.

Without an account, ricochet listen <target> creates a temporary URL that lasts 24 hours, with a live page; running it again resumes the same URL.

Argument or option	Meaning
[TARGET]	Without an account: where to forward, a port (3000), host:port or an http(s) URL.
--forward <URL[,source=S][,event-type=T]>	Where to forward your events: a port, host:port or http(s) URL, optionally only for one source or event type. Repeat for several targets.
--source <SOURCE>	Only this source (ID or name), for targets that name none. Repeatable.
--event-type <TYPE>	Only events of this type, for targets that name none. Repeatable.
--plain	One line per event instead of the full-screen view.
--new	Without an account: a new temporary URL instead of the saved one.

The full-screen view

On a terminal, listen shows a live list of events (starting with the environment’s stored ones) and, for the selected event, its headers, body and the answer of each target. It is plain output instead with --plain or when the output is piped.

Key	Action
↑ ↓, j k	Move; reaching the end loads older events.
PgUp PgDn, Home End	Move by a page, or to the first or last event.
/	Filter. source:, status: and type: words ask the API; other words match the rows.
r	Replay the selected event to all targets, recorded as a new attempt.
1–9	Send the stored request to that target only (not recorded).
e	Edit the body in $VISUAL or $EDITOR and resend it as a new event.
q, Esc, Ctrl-C	Quit.

ricochet replay

Delivers an event again, or every event that matches.

ricochet replay evt_01k6zv3f8ve8tb5m6bq6bnqh0r
ricochet replay --status failed --since 24h

With an event ID, it goes to the event’s original destinations, or to --destination. Without one, it makes a bulk replay job of the events that match, asks you to confirm the count, then starts it and shows its progress.

Argument or option	Meaning
[EVENT]	The event (evt_ ID).
--destination <DESTINATION>	Where to: a destination’s ID or name.
--status <STATUS>	Bulk: events with an original delivery in this state: failed, delivered or pending.
--since <SINCE>	Bulk: events received this recently, e.g. 30m, 24h, 7d. Default 24h.
--source <SOURCE>	Bulk: only this source (ID or name). Repeatable.
--event-type <TYPE>	Bulk: only events of this type. Repeatable.
--rate <RATE>	Bulk: replays started per second, 1 to 100 (default 10).
-y, --yes	Bulk: start without asking.

ricochet trigger

Sends a provider’s sample event to one of your sources, signed with the source’s secret as the provider would sign it. Without arguments it lists the samples.

ricochet trigger stripe payment_intent.succeeded
ricochet trigger github push --set ref=refs/heads/main --edit

Argument or option	Meaning
[PROVIDER]	The provider, stripe or github.
[EVENT_TYPE]	The event type, e.g. payment_intent.succeeded.
--source <SOURCE>	The source to send to (ID or name); needed when there are several and none is named after the provider.
--set <PATH=VALUE>	Change a field first, e.g. data.object.amount=500. Repeatable.
--edit	Open the payload in $EDITOR before sending.
--no-sign	Send it without a signature.

ricochet events

ricochet events list --status failed --since 1h
ricochet events get evt_01k6zv3f8ve8tb5m6bq6bnqh0r --json

events list prints the newest events first; events get <ID> prints one event with its headers, body and every delivery attempt.

Option (list)	Meaning
--source <SOURCE>	Only this source (ID or name).
--status <STATUS>	received, pending, delivered or failed.
--event-type <TYPE>	Only events of this type.
--since <SINCE>	Received this recently, e.g. 30m, 24h, 7d.
--limit <LIMIT>	How many (default 20).
--json	Print the API’s JSON (also on get).

ricochet sources

ricochet sources list
ricochet sources create billing

sources list prints every source in the environment with the URL providers send to. sources create <NAME> makes a source that accepts POSTs with no signature check; set its verification in the dashboard. Both take --json.

ricochet completion

Prints a shell completion script for bash, zsh, fish, powershell or elvish:

ricochet completion bash > ~/.local/share/bash-completion/completions/ricochet

Files

File	What it holds
.ricochet.json	The listen targets, project and environment for a directory. Commit it to share them with your team.
~/.config/ricochet/	Saved temporary URLs, and the sign-in token when there is no keychain. RICOCHET_CONFIG_DIR moves it; RICOCHET_KEYCHAIN=0 skips the keychain.

Exit codes

Code	Meaning
0	Done.
1	Failed.
2	Wrong arguments.
3	Sign in needed: run ricochet login.
4	Not found.
5	The server is unreachable or failing.