CLI

The Flint CLI (flint) is a terminal client for the public API. Every command maps to a documented /v1 route, so anything you can do over HTTP you can do from a shell, a script, or a CI job.

It is most useful for three things:

• Trying a payment flow without writing an integration first.
• Forwarding live sandbox webhook events to a local server with flint listen.
• Scripting the API in CI, where JSON output and stable exit codes matter more than pretty printing.

Install#

npm install -g @flintpay/cli

The npm package resolves a prebuilt binary for your platform. On macOS and Linux you can install it with Homebrew instead:

brew install flintpay/tap/flint

Prebuilt archives for macOS, Linux, and Windows are also attached to each release, with a checksums.txt to verify against.

Verify the install:

flint version

Authenticate#

If you already have an account, create a sandbox key in the dashboard and import it:

flint auth import

The command prompts for the key without echoing it, validates it against the API, and stores it in your OS keychain. It is never written to a config file. To import from a script, pipe it in:

flint auth import --stdin < key.txt

If you do not have an account yet, flint signup runs the same API-first onboarding flow described in API & Agent Onboarding: it collects your email, sends a verification code, completes machine-actionable onboarding steps, and stores the initial sandbox key as soon as the API makes it available. If a requested capability requires an embedded human verification step first, the command returns that onboarding state as an actionable error.

Then confirm everything is wired up:

flint doctor

doctor checks your config, credential, connectivity, environment, merchant, scopes, and whether your CLI build matches the API version the server reports. Each check prints pass or fail with a concrete fix. flint doctor --fix applies only the mechanical config repairs it proposed; it never touches credentials or server state.

flint init is the guided entry point: it runs the doctor checks if you are authenticated and prints the next steps below, or points you at auth import and signup if you are not.

Your first payment#

Create a hosted checkout session and open it in a browser:

flint checkout create \
  --quick-pay-name T-shirt \
  --amount 2500 \
  --currency USD \
  --open

Amounts are integers in the currency's smallest unit, so 2500 is $25.00. See Money & Currency.

To drive a payment entirely from the terminal, create a payment intent and confirm it with a sandbox payment source token:

flint payment-intents create --amount 2500 --currency USD --payment-option card
flint payment-intents confirm pi_123 --payment-source-token pm_card_visa

flint help test-cards prints the sandbox tokens and their matching test card numbers offline. More scenarios, including declines and 3D Secure, are in Testing.

For the full commerce flow, create an order and pay it:

flint orders create --input order.json
flint orders pay ord_123 --payment-source-token pi_456=pm_card_visa

Any command that takes a request body accepts --input file.json, or --input - to read from stdin.

Referring to the last resource#

The CLI records the IDs it creates and reads, so you can chain commands without copying IDs:

flint payment-intents create --amount 2500 --currency USD --payment-option card
flint payment-intents get @last.pi

@last.pi resolves to the most recent payment intent for the current profile and environment. The qualifier is the resource's ID prefix, so @last.ord is the last order and @last.cs the last checkout session. flint history lists what is stored; flint history --clear --confirm empties it.

Forward webhooks to localhost#

flint listen opens a stream of your sandbox's webhook events and forwards each one to a local URL, so you can develop against real events without a public tunnel:

flint listen --forward-to http://localhost:8080/webhooks/flint

It prints a signing secret on startup:

Webhook signing secret: whsec_...
Forwarding to http://localhost:8080/webhooks/flint

Forwarded requests are signed with that secret, so your local handler can run the same signature verification it runs in production. The secret is generated per session, so set it in your local environment each time you start listening. See Webhooks for the verification details.

Narrow the stream to the events you care about, and resume where you left off after a restart:

flint listen \
  --forward-to http://localhost:8080/webhooks/flint \
  --event-type payment_intent.succeeded \
  --cursor whev_123

The forward target must be a local address. flint listen is a development tool, not a delivery mechanism: to deliver events to a real service, register a webhook endpoint.

Waiting for async results#

Payments, refunds, and payouts settle asynchronously. Rather than polling by hand, block until a resource reaches the state you expect:

flint payment-intents get pi_123 --wait-for status=succeeded --for 60s

The command polls with backoff and exits 0 once the field matches. If the deadline passes first it exits 6 and still prints the last state it saw, so a CI job can tell "not yet" apart from "failed".

Scripting and CI#

For bounded commands, --output json prints one JSON envelope on stdout and switches off every prompt, so commands never block waiting for a TTY:

flint payment-intents list --status succeeded --output json

Streaming commands emit one listener, webhook event, delivery result, or checkpoint object per line. flint listen --output json requires --max-events or --for, which prevents automation from waiting forever. Use --output ndjson to opt into an intentionally unbounded stream; it still accepts either bound when you want one.

Diagnostics, progress, and prompts always go to stderr, so stdout stays a clean data stream. Useful flags when piping:

• --field PATH prints one value, unquoted, for direct capture into a shell variable.
• --select FIELDS narrows the output to specific fields.
• --jq EXPR applies a jq expression to the result.
• --all follows pagination and returns every page (see Pagination).
• --idempotency-key KEY sets the idempotency key on a write.
• --dry-run=client validates and prints the request the CLI would send, without calling the API.

Exit codes are stable, so scripts can branch on the failure class instead of parsing stderr:

flint help exit-codes prints the same catalog offline.

In CI, supply the key through the FLINT_API_KEY environment variable instead of the keychain. Set FLINT_OUTPUT=json and FLINT_NO_INPUT=1 to make every command non-interactive by default.

Sandbox and live safety#

The CLI derives the environment from the key itself, so there is no separate mode flag to get out of sync.

Live credentials require you to acknowledge production explicitly. Any command run with a flint_live_... key fails with LIVE_ACKNOWLEDGEMENT_REQUIRED until you pass --live. On top of that, destructive commands and sensitive writes in live mode prompt for confirmation; pass --confirm to acknowledge in advance, or --preview to see what would be affected without doing it.

For shared scripts, pin a profile to a specific merchant so a misconfigured key cannot act on the wrong account:

flint config set merchant mer_123

If the credential's merchant does not match the guard, the command fails before sending a request.

Raw API access#

When a route has no dedicated command, call it directly:

flint api get /v1/payment-intents/pi_123
flint api post /v1/payment-intents --input payment-intent.json
flint api get /v1/orders --paginate

flint api is an escape hatch over the documented public API, not an internal transport. It enforces the same auth, live-mode acknowledgement, confirmation, and error handling as first-class commands. --paginate follows next_page_token and emits one page envelope per line as NDJSON.

Debugging#

--debug prints the API version and trace ID for a request. When Flint returns an API error, the CLI prints its request_id, which you can look up directly:

flint request-logs list --status-bucket server_error
flint request-logs get rlog_123

flint timeline shows the full lifecycle of any supported resource, which is usually the fastest way to understand why something is in an unexpected state:

flint timeline pi_123

See Debugging for the wider request-tracing story.

Agents and MCP#

flint mcp serve runs a local MCP server over stdio that exposes commands safe for structured, non-interactive use as MCP tools, so an AI agent can act on your Flint account with your credential. Tool names are canonical command names such as payment-intents.create, and tool inputs are generated from the same command schemas. Import the credential before starting the server or provide it through FLINT_API_KEY; auth.import is intentionally not an MCP tool because secret keys must not pass through agent arguments.

flint mcp serve

This is different from the hosted MCP server, which is read-only and covers documentation. Use the hosted server so an agent can read docs and schemas; use flint mcp serve so an agent can create and inspect real resources in your sandbox.

For agents that call the CLI directly rather than over MCP, the schema commands make the surface machine-readable without scraping help text:

flint schema commands --output json
flint schema input payment-intents.create --output json
flint schema output payment-intents.create --output json
flint schema errors --output json
flint schema events --output json

An agent can list commands, fetch the input schema for the one it wants, build a request body mechanically, and validate it before spending a call. See LLM Integration.

Command reference#

CLI commands lists every command with its arguments, flags, examples, and the API route it calls. That page is generated from the catalog the binary itself serves, so it matches the version you have installed.

In the terminal, flint help lists the starting points and flint <command> --help documents any single command. For the same catalog as data:

flint schema commands --output json