CLI

@fianto/cli is the fianto command for development. It shows which application your keys belong to, reads your events, forwards them to a route on your machine, sends signed sample events, and signs a payload by hand. It holds your app secret: run it on your own machine or a trusted CI job.

InstallCopy Anchor Link

Run it without installing, or add it to your project:

npx @fianto/cli whoami

pnpm add -D @fianto/cli
pnpm exec fianto whoami

It needs Node.js 20.3 or later.

CredentialsCopy Anchor Link

The CLI reads your shell's environment, not a .env file: export the variables, or pass flags. Flags win over the environment.

The webhook secret comes from --secret, then --secret-file, then FIANTO_WEBHOOK_SECRET. trigger --forward-to and sign need only the webhook secret and make no API call. A missing credential is a usage error (exit 2) that names the flag and the variable to set.

CommandsCopy Anchor Link

fianto whoamiCopy Anchor Link

Calls GET /v1/application and prints the application's name and app id, the merchant's name, and the webhook's status and URL, or not configured.

npx @fianto/cli whoami

fianto events list [--type <type>] [--limit <n>]Copy Anchor Link

Prints one page of your events, newest first, one <id> <timestamp> <type> line each. --limit is 1 to 100, default 20.

npx @fianto/cli events list --type order.paid --limit 5

fianto events get <evt_id>Copy Anchor Link

Prints one event as indented JSON, as GET /v1/events/{id} returns it.

fianto events tail --forward-to <url>Copy Anchor Link

Polls your events and posts each new one to --forward-to, re-signed with your webhook secret the way Fianto signs a delivery. The body is the delivery envelope (id, type, timestamp, data). It runs until you press Ctrl-C.

npx @fianto/cli events tail \
  --forward-to http://localhost:3000/api/webhooks/fianto \
  --since 1h \
  --type order.paid

Each poll reads up to 100 events per page and follows the cursor until it has caught up. Each event is forwarded once per run, oldest first, with no retry. It prints → <status> <type> <id> <ms>ms per forward, ✗ <type> <id> <message> when your route could not be reached, and ✗ poll failed: … when a poll fails, then keeps polling. The first Ctrl-C lets the forward in flight finish and exits 130; a second one exits at once.

This is a development aid, not delivery: real deliveries go to your verified webhook URL, with retries.

fianto trigger <type>Copy Anchor Link

With --forward-to, signs a realistic local sample of any event type and posts it to that URL. No API call is made. The sample's ids are clearly fake, such as sample_order_1001.

npx @fianto/cli trigger subscription.created \
  --forward-to http://localhost:3000/api/webhooks/fianto \
  --secret "$FIANTO_WEBHOOK_SECRET"

It prints → <status> <type> (local sample). It does not follow redirects, and a status that is not 2xx exits 1. An unknown type exits 2 and lists the known ones.

Without --forward-to, only test.event works: Fianto sends a real, signed test.event to your application's verified webhook URL, and the CLI prints Sent test.event <evt_id> to your registered endpoint. This needs your app id and secret, and shares the limit of 10 test events per hour per application with the dashboard's test button. Any other type without --forward-to exits 2: Fianto never sends business events on request.

fianto sign --payload <file>Copy Anchor Link

Signs the exact bytes of a JSON file as Fianto would, then prints the body and a ready curl command, with $URL left for you to set. Every value in the curl line is shell-quoted.

npx @fianto/cli sign --payload event.json --secret "$FIANTO_WEBHOOK_SECRET"

fianto help, fianto --versionCopy Anchor Link

help, --help, or no command at all prints the usage and exits 0. --version or -v prints the installed version.

Exit codesCopy Anchor Link

See alsoCopy Anchor Link