Flute Webhooks CLI

Flute Webhooks CLI is a monitoring and debugging developer tool for Flute webhooks.

It is a command-line and TUI (terminal user interface) application that can display call statuses, inspect delivery logs, manage endpoints, and forward live webhook payloads. The tool can initiate and test webhook calls, including creating new webhooks and using existing ones. It supports all Flute webhook endpoints.

When an API call fails, Flute Webhooks CLI shows a sticky error modal. This is a display that stays on screen until dismissed. It shows the server's title, details, exceptionType, and a correlationID.

Download and install the application for your platform.
The latest installer can always be found at: https://github.com/getflute/flute-webhooks-cli/releases/latest.

macOS / Linux (cURL)
Use the following command to install the application for macOS or Linux using cURL.

curl -LsSf https://github.com/getflute/flute-webhooks-cli/releases/latest/download/flute-webhooks-cli-installer.sh | sh

macOS / Linux (Homebrew)
Use the following command to install the application for macOS or Linux using Homebrew.

brew install getflute/flute-webhooks-cli/flute-webhooks-cli

Windows (x64, PowerShell)

Use the following command from any location with either a Windows command window or a PowerShell window. This does not require elevated permissions.

powershell -ExecutionPolicy Bypass -c "irm https://github.com/getflute/flute-webhooks-cli/releases/download/v0.7.4/flute-webhooks-cli-installer.ps1 | iex"

After installing the application, close the command window. Re-open a command window.

To verify that the installation was successful, run:

• flute-webhooks --version

A version number should display.

To get a list of help commands, run:

• flute-webhooks --help

When launched, the application automatically checks for a newer version. If a newer version exists, a non-blocking notice displays.

To explicitly update the application, run:

• flute-webhooks update

For configuration options and saving them, see Configuring Flute Webhooks CLI.

Before using this application, you must be authenticated. Use your merchant or partner API key credentials.

To be authenticated as a user, use:

• flute-webhooks auth login

You will be prompted for your client_id and client_secret. The secret prompt is hidden.

The credentials are stored in your OS keychain and never written to disk in plain text. You are not required to authenticate each time you start this application. If your credentials later change, run this command again with the new credentials.

By default, credentials are stored for the sandbox profile. This is the same as using:

• flute-webhooks --profile sandbox auth login

To set up for production, use:

• flute-webhooks --profile production auth login

To display the current authentication key (used for the bearer token), run:

• flute-webhooks auth keys

Flute CLI runs in two modes: TUI (terminal user interface) mode and command line mode.

The TUI (terminal user interface) is a keyboard-driven, interactive, full-screen mode.

It runs inside the terminal but behaves more like a lightweight application. This includes menus, lists, and keyboard navigation you interact with in real time. You launch it and stay inside it to browse and view data, such as webhook endpoints, delivery logs, and event types.

To start the TUI, in a command window opened to any location, run:

• flute-webhooks tui

Use arrow keys to navigate rows, expand items, and toggle checkboxes. The following commands and keystrokes may be used to navigate Flute Webhooks CLI.

While typing in a text field, such as a URL or a name, single-character keys such as q, c, d, e, p, r, l, and t are treated as literal characters and do not trigger TUI commands.

The command line mode is a non-interactive mode.

Each invocation is a single command with arguments and flags that runs once, displays output, and exits. It's built for scripting, automation, and one-off lookups. Output can be piped into other tools, chained in CI, or run unattended. The command line mode issues instructions through the terminal and is scriptable.

For example:

flute-webhooks webhooks endpoints list
flute-webhooks --output json webhooks deliveries list --limit 15 | jq

In this example, the application jq must have been previously installed.

Endpoints The following is a list of endpoint commands the Flute Webhooks CLI can run.

flute-webhooks webhooks endpoints list
flute-webhooks webhooks endpoints get <id>
flute-webhooks webhooks endpoints create --url https://… --events transaction.card.refunded [--name "My Hook"]
flute-webhooks webhooks endpoints update <id> [--url …] [--events …] [--name …] [--status active|inactive]
flute-webhooks webhooks endpoints delete <id> --yes
flute-webhooks webhooks endpoints ping <id>

Event types

flute-webhooks webhooks event-types list

Delivery logs

flute-webhooks webhooks deliveries list [--endpoint-id <id>] [--status success|failed] [--limit 50]  # server caps page size at 100
flute-webhooks webhooks deliveries get <id>
flute-webhooks webhooks deliveries retry <id>

Headless listener

This forwards every new successful delivery's headers and body to a local URL. Runs in the foreground until Ctrl-C.

flute-webhooks listen --forward-to http://127.0.0.1:3000/webhook

Global flags (accepted on every subcommand)

--profile <sandbox|production>
--debug
--output table|json

--output json works on every CLI subcommand, producing pretty-printed JSON for piping into jq. To save output to a file instead of piping it, redirect stdout, for example:

flute-webhooks --output json webhooks deliveries list --limit 50 >> output.json

Every non-TUI subcommand also supports a structured JSON error envelope ({kind, message, status?, correlation_id?}) printed to stdout on failure, which makes Flute Webhooks CLI easier to drive from scripts and agents. See AGENTS.md in the flute-webhooks-cli repository for the full machine-readable contract.

Every documented Webhook API call is reachable from both TUI and CLI:

Pass --debug to log every HTTP request and response (status, URL, body):

flute-webhooks --debug auth keys    # traces print to stdout
flute-webhooks --debug tui          # traces go to ~/.flute/flute-webhooks.log

For non-TUI commands, traces print to stdout so you can pipe them through jq or grep. For the TUI, stdout is owned by the terminal renderer, so traces are appended to ~/.flute/flute-webhooks-cli.log. Open a second terminal and run tail -f ~/.flute/flute-webhooks-cli.log to watch live.

Response bodies are logged in full with no truncation, so the server stack traces are captured intact. The bearer token is never logged.

Without --debug, default tracing is INFO/WARN. Non-TUI commands write to stderr; the TUI writes to the log file.

An optional configuration file may be manually created at: ~/.flute/config.toml. The following are the valid key entry values.

This text may be pasted into that file. These represent the defaults. They may be changed to fit your needs.

default_profile = "sandbox"
poll_interval_seconds = 5
auto_update_check = true

In addition to the configuration file, Flute Webhooks CLI recognizes a small set of environment variables. These are useful for CI pipelines, scripting, and temporarily overriding a setting without editing config.toml.

Where a setting can be controlled more than one way, the command-line flag (such as --profile or --debug) takes precedence over its corresponding environment variable, which in turn takes precedence over the value in config.toml.

Unlike config.toml, environment variables are not written to disk or stored anywhere by Flute Webhooks CLI. They must be set in your shell or system environment each time you want them to apply — for example, exported in your shell profile (.bashrc, .zshrc) on macOS/Linux, or defined as a system or user environment variable on Windows. They take effect only for the process (or session) where they're set, and are not persisted by the application the way ~/.flute/config.toml is.

The following are the profile values associated with each environment.

To select a profile (global flag, accepted before or after the subcommand), use:
flute-webhooks --profile sandbox|production For example, flute-webhooks --profile sandbox sets the environment to sandbox.

The active profile is shown in the dashboard title.

MIT.