Flute CLI

Flute CLI is a cross-platform command-line interface for the Flute payments platform.

It covers the full transaction lifecycle for both card and ACH payments, including the customer vault, POS transactions, terminals and devices, settlement batches, subscriptions, and ISV API key management.

It ships as one self-contained executable, and every command can be scripted. Each one supports a structured JSON output mode with consistent exit codes and error envelopes, making Flute CLI well-suited to a shell script, CI pipeline, or AI agent rather than manual, interactive use.

Flute CLI is best suited to workflows where payments logic needs to run outside a browser session. The following are representative use cases.

Automation and CI/CD pipelines
Because every invocation is single-shot and non-interactive, flute commands integrate directly into shell scripts, deployment pipelines, and scheduled jobs. Combined with structured JSON output and semantic exit codes, this allows payment operations to be embedded in existing automation without a custom API integration.

Pre-production testing
During development, flute transactions sale and related commands let a developer validate card behavior, error handling, and webhook delivery against the sandbox environment directly from a terminal, ahead of writing SDK-based integration code.

Operational diagnostics
Support and operations engineers can inspect individual transactions, settlement batches, or terminal and device status without navigating a dashboard UI. The --debug flag surfaces the underlying HTTP request and response for cases requiring lower-level troubleshooting.

Reconciliation and reporting
Finance and operations teams can incorporate settlement batch data into scheduled reconciliation scripts, piping --output json results into downstream tooling such as jq for further processing.

Bulk account administration
For ISVs managing multiple merchants, the CLI supports scripted API key issuance and rotation, customer vault maintenance, and subscription lifecycle management at scale, in place of manual, one-at-a-time dashboard operations.

Agent and automation integration
The structured output envelope and semantic exit codes are designed to be consumed programmatically, allowing AI agents and other automated systems to invoke flute directly for tasks such as transaction lookups or refund issuance.

In general, flute is the appropriate tool where payments functionality must be driven by automation or scripting rather than interactive use; the dashboard remains the more direct path for one-off, manual operations.

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

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

brew install getflute/flute-cli/flute

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

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/getflute/flute-cli/releases/latest/download/flute-installer.sh | sh

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-cli/releases/latest/download/flute-installer.ps1 | iex"

Close the command window and open a new one to verify the installation.

To verify that the installation was successful, run either:

• flute version
• flute --version

To check the installed version, at any time, run:

• flute version

This displays Flute CLI version and active profile.

To get a list of general help commands, run:

• flute --help

To get a list of help commands for any command group, run:

• flute <group> --help

For help with specific command groups, see Displaying available commands

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 update

This downloads and installs the latest GitHub Release binary in place. If the CLI was built from source, this command prints a no-op message instead.

Before checking the status, you must be logged in.
To log in, see Authenticating the User

To check the status and functioning condition of the application, run:

• flute ping

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

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

To authenticate interactively, use:

• flute auth login

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

We recommend immediately checking the login status. Run:
flute auth status

Once entered, the credentials are stored in the OS keychain, keyed for each profile. There is no need to run this command again unless the credentials have changed or you log out. For example, this may be because of routine API key rotation or because the API key was compromised.

The auth command group also includes:

Flute CLI runs in a single, non-interactive mode. Each invocation is a single command with arguments and flags that runs once, displays output, and exits. This is intended for scripting, automation, and one-off lookups. Use a command window for all commands. Elevated permissions are not required.

The following example demonstrates charging a card. This example call uses the endpoint POST /pay-api/v1/transactions/sale. Use the following command. Of course, the card information must be valid.
flute transactions sale --amount 10.00 --card 4111111111111111 --exp 12/27 --cvv 123 --lineAddress1 "35 S. North Street" --zipCode "12345"

Flute CLI groups its functionality into command groups. Each covers one area of the payments platform, such as API endpoint groups. These range from authentication and card transactions to ACH, subscriptions, and API key management.

The table below lists each group alongside the subcommands it supports and a brief description of what it does. A complete, current list of groups and their available flags can be seen using:
flute --help

Groups that touch cardholder or bank data, such as transactions and customers, also accept AVS --billing-* flags for address verification.

The following is a list of available groups.

Every command group and subcommand in Flute CLI ships with its own contextual help. To see help for a specific command, run:
flute <group> --help
For example:
flute customers --help
This lists the subcommands available under that group, along with a short description of each.

More detailed help is also available for those subcommands. To see help for a specific subcommand, run:
flute <group> <subcommand> --help
For example:
flute customers create --help
This shows the exact flags, defaults, and examples for that specific action. This holds for every group in the command overview above, including any newly added to the API suite.

Output modes may be specified. They are controlled by:

• The command flag --output table|json|quiet
• The FLUTE_OUTPUT environment variable
• The output key in ~/.flute/config.toml

The format of the output is specified with:

For example:
flute transactions sale --amount 10.00 --card 4111111111111111 --exp 12/27 --cvv 123 --output json

--output json wraps every success response in a consistent envelope. The following is a snippet of the response.

{
  "object": "transaction_list",
  "data": {
    "filtered_count": 4,
    "items": [
      {
        "amount": {
          "baseAmount": 10.00,
          "cashDiscountAmount": 0,
          "cashDiscountRate": 0,
          "percentageOffAmount": 0.00,
  ...

Errors (non-zero exit codes) are also written to stdout as structured JSON when --output json is active. One of the response fields, kind, is any of api, transport, auth, decode, or client. The example below shows a typical response line:

{ "kind": "api", "message": "<error message>", "status": 422, "correlation_id": "<uuid>" }

Data always goes to stdout. Tracing, the production banner, and update notices always go to stderr. Parse one stream, never both.

Every flute invocation exits with one of five status codes. A script or CI pipeline can branch on the outcome without parsing the rest of the output. The code distinguishes a clean success from:

• An unexpected failure
• An authentication problem
• A validation or input error
• A not-found result

Each is mapped consistently regardless of which command produced it.

Under --output json, that same code also matches the kind reported in the error envelope. This allows callers reading structured output and callers checking $? to reach the same conclusion.

The following is a list of the exit codes.

Under --output json, CLI usage/parse errors are also written to stdout as a { "kind": "client", "message": … } envelope (exit 3). A machine consumer never gets an empty stdout on a bad invocation.

Flute CLI writes all logs to stderr. Command output goes to stdout. That split holds even with --debug. This means a flute --debug --output json … still emits a clean, parseable JSON document on stdout.

By default, only warnings and a few brief notices are logged. For example, a one-line note appears when a stale token triggers the automatic single 401 retry. Successful commands are otherwise quiet on stderr apart from the production banner.

The global --debug flag displays the full HTTP request/response traces (method, URL, status, and body) to stderr:

flute --debug ping
flute --debug transactions get <txn-id>

Sensitive fields are masked before anything is logged:

Masking lowers the risk but does not eliminate it. A --debug trace still reveals amounts, the last four digits, and request metadata. Avoid capturing --debug output into shared or long-lived logs when operating on production.

Setting RUST_LOG overrides the built-in filters entirely and accepts the standard EnvFilter syntax. The same field masking is applied to flute's own traces no matter how the level is set.

# Only flute's own HTTP traces, nothing from dependency crates
RUST_LOG=flute_cli=debug flute ping

# Add connection / TLS / DNS detail from the HTTP stack
RUST_LOG=flute_cli=debug,reqwest=debug,hyper=debug flute ping

Filter presets limit debug output to a chosen set of details.

Full debug output can be long and hard to scan. A preset shows only the parts needed for a task. For example, one preset can show only request and response headers. Another can show only response bodies, or only timing data. Presets apply only when --debug is set.

Each preset in this section lists its name, the details it includes, and an example command.

The table below shows the effective filter string each of these resolves to.

This section lists common ways to use the --debug option.

Each entry pairs a task with the command that performs it. Tasks include inspecting a failed request, capturing debug output to a file, and combining --debug with a specific profile. Use these entries to diagnose errors and verify request contents. Full details on debug output appear in the --debug reference.

Command errors are always printed to stderr (and to stdout as JSON under --output json) regardless of the log level.

Flute CLI's logging verbosity follows one of three presets, depending on how it's invoked.

• A plain command uses the quiet default.
• Warnings only. Adding --debug switches to a much noisier preset that includes HTTP traces from flute itself and its underlying connection libraries;
• Setting RUST_LOG directly overrides both, giving full control over exactly which modules log at which level.

Shell completions let the Tab key finish Flute CLI commands as they are typed.

A shell is the command window that runs the commands, such as bash, zsh or PowerShell. With completions installed, typing part of a command and pressing Tab fills in the rest. For example, typing flute trans and pressing Tab completes it to flute transactions. Pressing Tab twice lists the command groups, subcommands or flags available at that point. This reduces typing and prevents misspelled commands.

The table below shows where each supported shell loads its completion script.

Completions are optional, and Flute CLI works the same without them. To enable them, generate a completion script for the shell in use. Then install the script where that shell reads it at startup.

The following are supported shells.

# Bash
flute completion bash > /etc/bash_completion.d/flute

# Zsh (add to a directory on $fpath; for example, /usr/local/share/zsh/site-functions)
flute completion zsh > /usr/local/share/zsh/site-functions/_flute

# Fish
flute completion fish > ~/.config/fish/completions/flute.fish

# PowerShell
flute completion powershell >> $PROFILE

# Elvish
flute completion elvish >> ~/.config/elvish/rc.elv

An optional configuration file may be manually created at: ~/.flute/config.toml. It stores non-secret settings such as default_profile and output; credentials are always kept in the OS keychain, keyed per profile, never in the config file.

Precedence for all settings: flag > environment variable > profile config > global config.toml default.

Profiles store named sets of connection settings for the Flute CLI.

Each profile holds the settings for one context. These include the environment base URL, the API credentials, and the merchant or partner identity. Common examples are a sandbox profile and a production profile. Switching profiles changes the target of every command without re-entering credentials.

One profile acts as the default.
Use the --profile option to select a different profile for a single command. Set the FLUTE_PROFILE environment variable to change the profile for an entire session.

Profiles are stored locally in the Flute configuration file, ~/.flute/config. Keep separate profiles for merchant and partner API tokens. Many endpoints accept only one token type.

Running any command against production prints a red warning banner to stderr.

To select a profile, in order of highest precedence first:

1. Flag: --profile production
2. Environment variable: FLUTE_PROFILE=production
3. Config file default: ~/.flute/config.toml → default_profile = "production"

Every non-interactive command supports the structured --output json envelope described above, which makes Flute CLI straightforward to drive from scripts and agents.

For the full machine-readable contract, that is, structured output format, error JSON schema, exit codes, an idempotency table, and copy-pasteable command recipes for common agent intents. See agents.md in the flute-cli repository.

# Run all tests
cargo test

# Lint (zero warnings enforced)
cargo clippy --all-targets -- -D warnings

# Format check
cargo fmt --check

# Release build
cargo build --release

The codebase enforces #![forbid(unsafe_code)]. There is zero unsafe Rust. Design documents and the API spec live under docs/.

MIT.